Relay Portfolio Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require dbp/relay-portfolio-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       DigitalBlueprint\RelayPortfolioBundle\RelayPortfolioBundle::class => ['all' => true],
   ];
   

2. Publish Configuration Run:

   php bin/console dbp:relay-portfolio:install
   

   This generates:

   • Migrations (database/migrations/...)
   • Configuration (config/packages/relay_portfolio.yaml)
   • Optional assets (if enabled)

3. First Use Case: Basic Portfolio Entry Create a portfolio entry via CLI:

   php bin/console dbp:relay-portfolio:create
   

   Follow prompts to define a project (title, description, tags, etc.). Verify in database or via:

   php bin/console dbp:relay-portfolio:list
   

4. Key Configuration Review config/packages/relay_portfolio.yaml for:

   • default_locale (e.g., en)
   • storage (local filesystem or S3 for assets)
   • routing (prefix, e.g., /portfolio).

Implementation Patterns

Core Workflows

1. CRUD via CLI

   • Create: dbp:relay-portfolio:create (interactive or JSON input). Example JSON input:

     php bin/console dbp:relay-portfolio:create --json '{"title": "Laravel App", "description": "A SaaS platform", "tags": ["laravel", "sass"]}'
     

   • Update: dbp:relay-portfolio:edit <id> (interactive or JSON).
   • Delete: dbp:relay-portfolio:delete <id>.
   • List: dbp:relay-portfolio:list (filter by tags/date).

2. Asset Management Upload assets (images, PDFs) via:

   php bin/console dbp:relay-portfolio:upload <id> <path/to/file>
   

   Configure storage in relay_portfolio.yaml:

   storage:
       driver: 'local' # or 's3'
       path: '%kernel.project_dir%/public/uploads/portfolio'
       s3:
           bucket: 'my-bucket'
           key: 'my-key'
   

3. API Endpoints The bundle auto-generates API routes under /api/portfolio:

   • GET /api/portfolio (list with pagination).
   • GET /api/portfolio/{id} (single entry).
   • POST/PUT/DELETE for CRUD (authenticated via ROLE_PORTFOLIO_EDITOR).

4. Twig Integration Access portfolio entries in templates:

   {% for project in app.service('relay_portfolio.manager').findAll() %}
       <h2>{{ project.title }}</h2>
       <img src="{{ asset(project.coverImageUrl) }}" alt="{{ project.title }}">
   {% endfor %}
   

5. Event-Driven Extensions Listen to portfolio events (e.g., PortfolioEntryCreated) in EventSubscribers:

   namespace App\EventListener;
   
   use DigitalBlueprint\RelayPortfolioBundle\Event\PortfolioEntryEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class PortfolioNotifier implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               PortfolioEntryEvent::CREATED => 'onPortfolioCreated',
           ];
       }
   
       public function onPortfolioCreated(PortfolioEntryEvent $event)
       {
           // Send notification (e.g., Slack, email)
       }
   }
   

Integration Tips

1. Authentication Secure API routes by adding guards to security.yaml:

   access_control:
       - { path: ^/api/portfolio, roles: ROLE_PORTFOLIO_EDITOR }
   

   Create a custom role in security.yaml:

   role_hierarchy:
       ROLE_PORTFOLIO_EDITOR: [ROLE_USER]
   

2. Custom Fields Extend the PortfolioEntry entity by creating a custom field type:

   // src/Entity/PortfolioExtension.php
   namespace App\Entity;
   
   use DigitalBlueprint\RelayPortfolioBundle\Entity\PortfolioEntry;
   use Doctrine\ORM\Mapping as ORM;
   
   #[ORM\Entity]
   class PortfolioExtension
   {
       #[ORM\Id]
       #[ORM\GeneratedValue]
       #[ORM\Column]
       private ?int $id = null;
   
       #[ORM\OneToOne(targetEntity: PortfolioEntry::class, inversedBy: 'extension')]
       private PortfolioEntry $portfolioEntry;
   
       #[ORM\Column(type: 'json')]
       private array $customData = [];
   
       // Getters/setters...
   }
   

   Register the extension in the bundle’s configuration.

3. Testing Use the bundle’s test utilities in PHPUnit:

   use DigitalBlueprint\RelayPortfolioBundle\Tests\PortfolioTestCase;
   
   class MyPortfolioTest extends PortfolioTestCase
   {
       public function testCreatePortfolioEntry()
       {
           $entry = $this->createPortfolioEntry(['title' => 'Test']);
           $this->assertEquals('Test', $entry->getTitle());
       }
   }
   

Gotchas and Tips

Pitfalls

1. Migration Conflicts

   • If you modify the PortfolioEntry entity after initial setup, drop and recreate migrations:

     php bin/console doctrine:migrations:diff
     php bin/console doctrine:migrations:migrate
     

   • Avoid manual schema edits; use Doctrine migrations.

2. Storage Permissions

   • Ensure the storage path in relay_portfolio.yaml is writable:

     chmod -R 775 %kernel.project_dir%/public/uploads/portfolio
     

   • For S3, verify IAM permissions and bucket policies.

3. Locale Handling

   • The bundle defaults to en. To add multilingual support:

     # config/packages/relay_portfolio.yaml
     locales: [en, fr]
     

   • Translate fields via trans() in Twig:

     {{ 'portfolio.label.title'|trans }}
     

4. Event Dispatching

   • Events may not trigger if the bundle isn’t properly registered. Verify in services.yaml:

     DigitalBlueprint\RelayPortfolioBundle\:
         resource: '../vendor/digital-blueprint/relay-portfolio-bundle/src/'
         exclude: '../vendor/digital-blueprint/relay-portfolio-bundle/src/{Entity,Tests,DependencyInjection/Configuration.php}'
     

5. API Rate Limiting

   • The API endpoints lack built-in rate limiting. Add it in config/packages/security.yaml:

     firewalls:
         main:
             rate_limiting:
                 api_portfolio:
                     path: ^/api/portfolio
                     limit: 60
     

Debugging Tips

1. Log Entries Enable debug logging in config/packages/monolog.yaml:

   handlers:
       main:
           type: stream
           path: "%kernel.logs_dir%/%kernel.environment%.log"
           level: debug
           channels: ["!event"]
   

   Filter for relay_portfolio:

   grep -i "relay_portfolio" %kernel.logs_dir%/dev.log
   

2. Doctrine Debugging Dump portfolio entries:

   use Doctrine\ORM\EntityManagerInterface;
   
   class DebugController
   {
       public function __construct(private EntityManagerInterface $em) {}
   
       public function dumpPortfolio()
       {
           $entries = $this->em->getRepository(DigitalBlueprint\RelayPortfolioBundle\Entity\PortfolioEntry::class)->findAll();
           dd($entries);
       }
   }
   

3. CLI Verbosity Increase CLI output for commands:

   php bin/console dbp:relay-portfolio:create -v
   

Extension Points

1. Custom Validators Add validation to portfolio entries by creating a custom constraint:

   namespace App\Validator;
   
   use Symfony\Component\Validator\Constraint;
   
   #[Attribute]
   class UniqueTag
   {
       public string $message = 'This tag already exists.';
   }
   

   Register it in services.yaml:

   App\Validator\UniqueTagValidator: ~
   

2. Custom Templates Override Twig templates by copying them from:

   vendor/digital-blueprint/relay-portfolio-bundle/src/Resources/views/
   

   to:

   templates/bundles/relayportfolio/
   

3. **Graph