Corebundle Laravel Package

Getting Started

Minimal Steps

1. Installation Run composer require coresite/corebundle in your Symfony 3 project root. Ensure composer.json includes "symfony/symfony": "^3.0" as a dependency.

2. Bundle Registration Add new CoreSite\CoreBundle\CoreSiteCoreBundle() to AppKernel::registerBundles(). Clear cache: php bin/console cache:clear.

3. First Use Case Check if the bundle provides:

   • Base templates (e.g., CoreSiteCoreBundle::layout.html.twig).
   • Default routes (verify via php bin/console debug:router).
   • Configuration (check config/packages/core_site_core.yaml if auto-generated).

4. Where to Look First

   • Bundle Structure: Explore vendor/coresite/corebundle/Resources/ for templates, assets, and configs.
   • Documentation: Review the README for Symfony 3-specific quirks (e.g., dependency injection, event listeners).
   • Symfony Docs: Cross-reference with Symfony 3 Bundle Development for missing details.

Implementation Patterns

Core Workflows

1. Extending Templates Override bundle templates by copying them to templates/CoreSiteCoreBundle/ in your project. Example: Extend layout.html.twig to add custom header/footer logic.

   {# templates/CoreSiteCoreBundle/layout.html.twig #}
   {% extends 'CoreSiteCoreBundle:layout.html.twig' %}
   {% block title %}{{ parent() }} | My Custom Title{% endblock %}
   

2. Routing Integration

   • Prefix Routes: Use core_site_core_* routes as base paths (e.g., /admin/*).
   • Custom Routes: Define new routes in config/routes/core_site_core.yaml:

     core_site_custom:
         resource: "@CoreSiteCoreBundle/Resources/config/routing/custom.yaml"
         prefix: /custom
     

3. Configuration

   • Parameters: Define in config/packages/core_site_core.yaml:

     core_site_core:
         default_locale: 'en'
         debug_mode: '%kernel.debug%'
     

   • Services: Extend bundle services via services.yaml:

     services:
         App\Service\CustomCoreService:
             decorates: 'core_site_core.service.default'
             arguments: ['@.inner']
     

4. Event Listeners Subscribe to bundle events (e.g., core_site_core.event.template_override):

   // src/EventListener/CustomTemplateListener.php
   namespace App\EventListener;
   use CoreSite\CoreBundle\Event\TemplateOverrideEvent;
   
   class CustomTemplateListener {
       public function onTemplateOverride(TemplateOverrideEvent $event) {
           $event->setTemplate('custom_path.html.twig');
       }
   }
   

   Register in services.yaml:

   services:
       App\EventListener\CustomTemplateListener:
           tags:
               - { name: 'kernel.event_listener', event: 'core_site_core.template_override' }
   

5. Asset Management Override CSS/JS by copying files from vendor/coresite/corebundle/Resources/public/ to public/bundles/coresitecore/.

Integration Tips

• Symfony 3 Compatibility: Avoid Symfony 4+ features (e.g., autoconfigure, make:controller).
• Debugging: Use bin/console debug:container to inspect bundle services.
• Testing: Mock bundle services in PHPUnit:

  $this->container->set('core_site_core.service.default', $this->createMock(CoreService::class));
  

Gotchas and Tips

Pitfalls

1. Namespace Collisions

   • The bundle uses CoreSite\CoreBundle; avoid naming conflicts with your project’s CoreBundle.
   • Fix: Rename your bundle or adjust autoloading in composer.json:

     "autoload": {
         "psr-4": { "App\\": "src/", "CoreSite\\CoreBundle\\": "vendor/coresite/corebundle/" }
     }
     

2. Missing Symfony 3 Features

   • No support for Symfony Flex or auto-wiring. Manually define services in services.yaml.
   • Workaround: Use AppKernel for bundle registration (no config/bundles.php).

3. Template Overrides

   • Forgetting to clear cache after template changes:

     php bin/console cache:clear --env=dev --no-debug
     

   • Tip: Use {% debug %} in Twig to verify template inheritance.

4. Configuration Overrides

   • Bundle configs may not auto-load. Explicitly include them in AppKernel:

     $bundles[] = new CoreSite\CoreBundle\CoreSiteCoreBundle();
     $this->import('config/packages/core_site_core.yaml');
     

5. Deprecated Symfony 3 APIs

   • Avoid Kernel::shutdown(); use KernelEvents::TERMINATE instead.
   • Check: Run php bin/console debug:container --invalid to find deprecated services.

Debugging

• Service Not Found: Verify the service is registered in CoreSiteCoreBundle/Resources/config/services.yaml.
• Route Not Found: Ensure the route is loaded in routing.yml and the bundle is enabled in AppKernel.
• Twig Errors: Check for missing blocks in extended templates:

  {% block body %}{% endblock %}  {# Required if parent template expects it #}
  

Extension Points

1. Custom Controllers Extend bundle controllers by creating a new controller and overriding actions:

   // src/Controller/CustomCoreController.php
   namespace App\Controller;
   use CoreSite\CoreBundle\Controller\CoreController;
   
   class CustomCoreController extends CoreController {
       public function customAction() {
           return $this->render('custom_template.html.twig');
       }
   }
   

   Register the route in routing.yml:

   custom_core:
       path: /custom
       defaults: { _controller: 'App\Controller\CustomCoreController::customAction' }
   

2. Database Migrations If the bundle includes migrations (e.g., DoctrineMigrations), run:

   php bin/console doctrine:migrations:execute --up --query="SELECT * FROM migration_versions WHERE version='CoreSiteCoreBundle\Migration\VersionYYYYMMDDHHMMSS'"
   

3. Translation Overrides Override translations in translations/messages.en.yaml:

   CoreSiteCoreBundle:
       hello: 'Custom Hello Message'
   

Pro Tips

• Bundle Isolation: Use bin/console debug:bundle to list all loaded bundles and verify CoreSiteCoreBundle is active.
• Performance: Disable debug mode in production to avoid template recompilation:

  # config/packages/dev/core_site_core.yaml
  core_site_core:
      debug_mode: true
  

• Community: Check for open issues on GitHub (low stars may indicate untested features).