Getting Started

Minimal Setup in Laravel (Legacy Context)

Since this bundle is part of the Symfony CMF ecosystem (not natively Laravel-compatible), you’d need to integrate it via Symfony’s components or a Laravel bridge. Here’s how a Laravel dev might approach it:

Install via Composer (for legacy projects or experimentation):
```
composer require symfony-cmf/resource-rest-bundle
```
Note: This requires Symfony’s dependency stack (e.g., symfony/framework-bundle).

Configure Puli Resources (CMF’s resource system):

Define a PuliResource entity (e.g., Article, Media) with metadata like uri, mimeType, and content.

Example:

use Symfony\Cmf\Component\Resource\ResourceInterface;
use Symfony\Cmf\Component\Resource\ResourceTrait;

class Article implements ResourceInterface
{
    use ResourceTrait;
    // Add fields like title, body, etc.
}

Register the Bundle (if using Symfony’s Kernel):

// config/bundles.php (Symfony)
return [
    Symfony\Cmf\ResourceRestBundle\ResourceRestBundle::class => ['all' => true],
];

First API Endpoint:
- The bundle auto-generates REST routes for Resource entities (e.g., /api/articles).
- Test with:
```
php artisan route:list  # (Symfony) or check Symfony’s router
```
Laravel Workaround:
- Use Symfony’s HttpKernel in Laravel via symfony/http-kernel or wrap routes in a Lumen/Symfony bridge.
- Example: Proxy requests to a Symfony microkernel.

Implementation Patterns

1. Resource-Centric API Design

Pattern: Treat entities as "resources" with GET, POST, PUT, DELETE endpoints.

Example:

# config/packages/symfony_cmf_resource_rest.yaml (Symfony)
cmf_resource_rest:
    routes:
        - { path: '/api/articles', resource: 'article', methods: [GET, POST] }

Laravel Adaptation: Manually route to Symfony’s kernel or use a facade:

Route::get('/api/articles', function () {
    return app(Symfony\Cmf\ResourceRestBundle\ResourceRestBundle::class)
        ->getRestHandler()
        ->handleRequest(Request::create('/api/articles', 'GET'));
});

2. Serialization with JMS Serializer

The bundle relies on JMS Serializer for JSON conversion.

Pattern: Annotate entities for serialization:

use JMS\Serializer\Annotation as Serializer;

class Article
{
    /**
     * @Serializer\Type("string")
     */
    public $title;
}

Gotcha: Ensure jms/serializer-bundle (≥2.2) is installed.

3. Custom Handlers

Extend ResourceHandler to modify behavior:

use Symfony\Cmf\ResourceRestBundle\Handler\ResourceHandler;

class CustomArticleHandler extends ResourceHandler
{
    public function handleGet(Request $request, Article $article)
    {
        // Add custom logic (e.g., access control)
        return parent::handleGet($request, $article);
    }
}

cmf_resource_rest:
    handlers:
        article: App\Handler\CustomArticleHandler

4. Integration with Laravel’s Eloquent

Pattern: Use a data mapper to bridge CMF Resource and Eloquent models:

class ArticleMapper
{
    public function toResource(array $data): Article
    {
        $article = new Article();
        $article->setUri('/articles/' . $data['id']);
        $article->setContent($data['body']);
        return $article;
    }
}

5. Authentication/Authorization

Pattern: Use Symfony’s security component or Laravel’s middleware:

// Symfony
cmf_resource_rest:
    security:
        article:
            - ROLE_USER

Laravel: Wrap routes in auth:api middleware.

Gotchas and Tips

1. Legacy Dependencies

Gotcha: Requires Symfony 4.4+ (PHP 7.2+) and JMS Serializer.
Tip: For Laravel, consider:
- Using Symfony’s HttpKernel in a separate service.
- Replacing with API Platform or Laravel’s built-in API tools (e.g., spatie/laravel-fractal).

2. Serialization Issues

Gotcha: JMS Serializer may fail on circular references or unsupported types.
Tip:
- Use @Serializer\MaxDepth to limit recursion.
- For Laravel, switch to Fractal or Laravel’s JSON responses:
```
return response()->json($article->toArray());
```

3. Routing Conflicts

Gotcha: Symfony’s auto-routing may clash with Laravel’s.
Tip:
- Prefix CMF routes (e.g., /api/cmf/*).
- Use Symfony’s Router in a separate domain/subdomain.

4. Performance

Gotcha: Puli’s resource system adds overhead for large datasets.
Tip:
- Cache responses with Symfony’s HttpCache.
- Paginate results:
```
cmf_resource_rest:
    pagination:
        article: 20
```

5. Debugging

Tip: Enable Symfony’s profiler:

// config/packages/dev/debug.yaml
framework:
    profiler: { only_exceptions: false }

Laravel: Use dd($request->getContent()) to inspect raw input.

6. Extending Functionality

Tip: Override ResourceRestBundle services:

services:
    App\Custom\ResourceRestBundle:
        decorates: 'cmf_resource_rest.resource_rest'
        arguments: ['@App\Custom\ResourceRestBundle.inner']

Example: Add CORS headers:

public function handleRequest(Request $request)
{
    $response = $this->getInner()->handleRequest($request);
    $response->headers->set('Access-Control-Allow-Origin', '*');
    return $response;
}

7. Testing

Tip: Use Symfony’s WebTestCase:

public function testGetArticle()
{
    $client = static::createClient();
    $client->request('GET', '/api/articles/1');
    $this->assertEquals(200, $client->getResponse()->getStatusCode());
}

Laravel: Mock the Symfony kernel or use Http::fake().

8. Alternatives

For Laravel: Consider:
- API Platform (for resource APIs).
- Laravel Sanctum/Passport (for auth).
- Spatie’s Laravel API Resources (for serialization).
For Symfony: Use API Platform or Nelmio API DocBundle.


---
```markdown
## Final Note
While this bundle is **abandoned**, its patterns (resource-based REST, JMS Serializer, custom handlers) are still valuable. For Laravel, evaluate whether the complexity justifies integration or if modern alternatives (e.g., **Laravel Sanctum + API Resources**) suffice.

Resource Rest Bundle Laravel Package