Resource Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require symfony-cmf/resource
   

   Ensure your project uses PHP 7.1/7.2 and Symfony (tested with Symfony 4.x, though legacy support exists).

2. Dependencies:

   • Requires PHPCR/ODM (for PHPCR integration) and Puli (resource management).
   • Configure puli and phpcr_odm bundles in config/bundles.php:

     return [
         // ...
         Symfony\Cmf\Resource\PuliResourceBundle::class => ['all' => true],
         Symfony\Cmf\Bundle\PhpcrBundle\PhpcrBundle::class => ['all' => true],
         Puli\Bundle\PuliBundle::class => ['all' => true],
     ];
     

3. First Use Case: Locate a resource (e.g., a document) from PHPCR using Puli:

   use Symfony\Cmf\Resource\PuliResource\PuliResourceLocator;
   use Puli\Resource\ResourceInterface;
   
   $locator = $container->get(PuliResourceLocator::class);
   $resource = $locator->getResource('/path/to/document.xml'); // Returns ResourceInterface
   

Implementation Patterns

Core Workflows

1. Resource Resolution:

   • Use PuliResourceLocator to fetch resources from PHPCR via Puli.
   • Example: Resolve a template or static asset dynamically:

     $resource = $locator->getResource('/templates/home.html.twig');
     $content = $resource->getContent(); // Stream or string content
     

2. Integration with Symfony Components:

   • Twig: Pass resolved resources to Twig templates:

     {{ resource.content|raw }} {# Render raw content #}
     

   • HttpFoundation: Stream resources directly to responses:

     $response = new StreamedResponse(function () use ($resource) {
         $resource->rewind();
         stream_copy_to_stream($resource, $this->get('response')->getBody());
     });
     

3. Event-Driven Extensions:

   • Listen to puli.resource.located events to intercept/resource resolution:

     $dispatcher->addListener('puli.resource.located', function (ResourceLocatedEvent $event) {
         if ($event->getResource()->getPath() === '/special/path') {
             $event->setResource($customResource);
         }
     });
     

4. PHPCR + Puli Sync:

   • Use PuliResourceManager to sync PHPCR nodes with Puli resources:

     $manager = $container->get('puli.resource.manager');
     $manager->sync(); // Syncs PHPCR changes to Puli
     

Integration Tips

• Caching: Leverage Puli’s cache layer to avoid repeated PHPCR queries.
• Fallbacks: Implement custom ResourceLocator implementations for non-PHPCR backends (e.g., filesystem).
• Testing: Mock ResourceInterface in unit tests:

  $mockResource = $this->createMock(ResourceInterface::class);
  $mockResource->method('getContent')->willReturn('mocked content');
  

Gotchas and Tips

Pitfalls

1. Deprecation Warnings:

   • The package is abandoned (last release: 2018). Avoid in new projects; prefer alternatives like:
     • Symfony’s AssetComponent for static assets.
     • Doctrine PHPCR ODM + custom resolvers for dynamic content.
   • Puli’s instability may cause runtime errors (e.g., ClassNotFoundException for internal APIs).

2. PHPCR Dependency:

   • Requires a PHPCR-compatible backend (e.g., Jackrabbit, eZ Publish). Misconfiguration leads to:

     // Throws if PHPCR session is invalid
     $locator->getResource('/nonexistent/path');
     

3. Resource Paths:

   • Paths are case-sensitive and must match PHPCR node paths exactly.
   • Trailing slashes (/path/) vs. no slashes (/path) may cause ResourceNotFoundException.

4. Event System:

   • Events like puli.resource.located are internal and may change. Avoid relying on them in production.

Debugging

• Enable Puli Debugging:

  # config/packages/puli.yaml
  puli:
      debug: true
  

  Logs resource resolution steps to Symfony’s debug toolbar.

• Check PHPCR Session: Verify the session is active:

  $session = $container->get('phpcr.odm.session');
  if (!$session->isLive()) {
      throw new \RuntimeException('PHPCR session is not connected!');
  }
  

Extension Points

1. Custom Resource Locators: Extend AbstractResourceLocator to support new backends:

   class CustomLocator extends AbstractResourceLocator
   {
       public function getResource($path)
       {
           return new FilesystemResource('/custom/path/' . $path);
       }
   }
   

2. Puli Resource Adapters: Create adapters to bridge other storage systems (e.g., S3) with Puli’s ResourceInterface.

3. Configuration Overrides: Override Puli’s default resource manager in config/packages/puli.yaml:

   puli:
       resource_manager: your_custom.manager.service_id
   

Pro Tips

• Use ResourceInterface Polymorphism: Implement custom methods on your resource classes (e.g., getMetadata()) for domain-specific logic.
• Batch Resolution: For performance, resolve multiple resources in a single PHPCR query:

  $resources = $locator->getResources(['/path1', '/path2']);
  

• Fallback to Filesystem: Combine with Symfony\Component\Asset\Packages for hybrid PHPCR/filesystem setups.