kriswallsmith/assetic — pull request #576 by webmozart (2014-02-25 17:41:14+00:00)
Title: Refactored resource loading logic out of the resources

I think that the current resource classes are very hard to understand (I spent a lot of time figuring out what they do). IMO that's because they have too many responsibilities:

* they represent resources
* they load resources (in case of DirectoryResource and CoalescingDirectoryResource)

For this reason, I refactored the resource loading logic out of the resource classes. DirectoryResource and CoalescingDirectoryResource are deprecated now. Their `getFresh()` and `getContent()` methods don't seem to be used at all.

If we need resource collections with collective `getFresh()` and `getContent()` methods, I suggest adding a `ResourceCollection` class instead and use that instead of arrays. So far, that didn't seem necessary.

Before:

```php
$directory = new DirectoryResource('/views', '.twig');
$file = new FileResource('/bundle/views/layout.html.twig');

$am->setLoader('am', $loader);
$am->addResource($directory, 'twig');
$am->addResource($file, 'twig');
```

After:

```php
$loader = new DirectoryLoader();
$file = new FileResource('/bundle/views/layout.html.twig');

$am->setLoader('am', $loader);

foreach ($loader->load('/views', '.twig') as $entry) {
$am->addResource($entry, 'twig');
}
$am->addResource($file, 'twig');
```

For me, this is much easier to grasp.

Once the deprecation phase is over and `DirectoryResource` removed, the code for iterating directories can be removed from `CachedFormulaLoader`. Again, this makes sense in my opinion. All other formula loaders take resources which correspond to files, so passing directory resources here is confusing for me.

Before:

```
$directory = new DirectoryResource('/views', '.twig');
$loader = new TwigFormulaLoader($twig);
$cachedLoader = new CachedFormulaLoader($loader, $cache);

// doesn't work
$loader->load($directory);

// works (huh?)
$cachedLoader->load($directory);
```

After:

```
$directoryLoader = new DirectoryLoader();
$formulaLoader = new TwigFormulaLoader($twig);
$cachedLoader = new CachedFormulaLoader($loader, $cache);

$files = $directoryLoader->load('/views', '.twig');

foreach ($files as $file) {
$loader->load($file);
// or
$cachedLoader->load($file);
}
```

Since I don't know what the backwards compatibility policy is for Assetic, I left all existing code in as deprecated and did not introduce any BC breaks.