Core Laravel Package

Getting Started

Minimal Steps

1. Install the Package Require the package via Composer in your Laravel project:

   composer require draw/core
   

2. Register the Service Provider Add the DrawCoreServiceProvider to your config/app.php under the providers array:

   'providers' => [
       // ...
       Draw\Core\Providers\DrawCoreServiceProvider::class,
   ],
   

3. Configure Ignored Annotations Create or update config/draw.php to specify annotations to ignore:

   return [
       'ignored_annotations' => [
           'Some\NonDraw\Annotation\Route',
           'Another\Namespace\ParamConverter',
       ],
   ];
   

   (Alternatively, use the provided ignore_annotations.php example as a reference.)

4. First Use Case: Resolve Annotation Errors If your Laravel app uses Doctrine’s AnnotationReader and encounters errors like:

   Doctrine\Common\Annotations\AnnotationException: [Semantical Error] The annotation "@Route" in class ...
   

   The package will automatically ignore draw-namespaced or configured annotations, eliminating the error.

Implementation Patterns

Workflows

1. Annotation-Heavy Projects

   • Pattern: Use draw/core to centralize ignored annotations in config/draw.php.
   • Example:

     // app/Providers/AppServiceProvider.php
     use Draw\Core\AnnotationIgnorer;
     public function boot() {
         AnnotationIgnorer::ignore(config('draw.ignored_annotations'));
     }
     

2. Modular Component Libraries

   • Pattern: Share draw/core across multiple Laravel packages to avoid duplicate annotation configurations.
   • Example:

     // In a shared package's composer.json
     "require": {
         "draw/core": "^1.0"
     }
     

3. Dynamic Annotation Handling

   • Pattern: Load ignored annotations dynamically (e.g., from a database or environment variable).
   • Example:

     $ignored = cache()->remember('draw.ignored_annotations', now()->addHours(1), function() {
         return config('draw.ignored_annotations');
     });
     AnnotationIgnorer::ignore($ignored);
     

Integration Tips

• Doctrine Integration Bind the AnnotationReader in Laravel’s service container to use the ignorer:

  // app/Providers/DrawCoreServiceProvider.php
  use Doctrine\Common\Annotations\AnnotationReader;
  public function register() {
      $this->app->singleton(AnnotationReader::class, function($app) {
          $reader = new AnnotationReader();
          $reader->addIgnoredNamespace(config('draw.ignored_annotations'));
          return $reader;
      });
  }
  

• Laravel Artisan Commands Use the package to validate annotations during command execution:

  use Draw\Core\AnnotationValidator;
  public function handle() {
      if (!AnnotationValidator::validate($this->getAnnotations())) {
          $this->error('Invalid annotations detected.');
      }
  }
  

• Testing Mock the AnnotationIgnorer in PHPUnit tests to simulate ignored annotations:

  $ignorer = $this->createMock(AnnotationIgnorer::class);
  $ignorer->method('ignore')->willReturn(true);
  $this->app->instance(AnnotationIgnorer::class, $ignorer);
  

Gotchas and Tips

Pitfalls

1. False Ignores

   • Issue: Overly broad ignored annotations (e.g., *) may suppress valid annotations.
   • Fix: Use precise namespace/annotation class names in config/draw.php.

2. Doctrine Version Conflicts

   • Issue: draw/core may not support newer doctrine/annotations versions.
   • Fix: Pin the Doctrine version in composer.json:

     "require": {
         "doctrine/annotations": "^1.13"
     }
     

3. Circular Dependencies

   • Issue: If draw/core is used in a package that also depends on Doctrine, circular requires may occur.
   • Fix: Use composer.json replace or conflict directives.

4. Annotation Reader Initialization

   • Issue: The ignorer must be registered before any AnnotationReader is instantiated.
   • Fix: Ensure DrawCoreServiceProvider is loaded early in Laravel’s boot process.

Debugging

• Enable Logging Add debug logs for ignored annotations:

  AnnotationIgnorer::setLogger(function($message) {
      \Log::debug('[Draw/Core]', [$message]);
  });
  

• Validate Config Use Artisan commands to verify ignored annotations:

  // In a custom Artisan command
  public function handle() {
      $ignored = config('draw.ignored_annotations');
      foreach ($ignored as $annotation) {
          if (!class_exists($annotation)) {
              $this->error("Annotation {$annotation} does not exist.");
          }
      }
  }
  

Extension Points

1. Custom Ignore Logic Extend the AnnotationIgnorer to add dynamic rules:

   class CustomAnnotationIgnorer extends \Draw\Core\AnnotationIgnorer {
       public function ignore($annotations) {
           // Add custom logic (e.g., ignore based on environment)
           parent::ignore($annotations);
       }
   }
   

2. Annotation Validation Implement a validator to check annotations against business rules:

   use Draw\Core\AnnotationValidator;
   class MyValidator extends AnnotationValidator {
       protected function rules() {
           return [
               'Some\Annotation' => ['method' => 'validateMethod'],
           ];
       }
   }
   

3. Integration with Laravel Events Trigger events when annotations are ignored:

   AnnotationIgnorer::onIgnore(function($annotation) {
       event(new AnnotationIgnored($annotation));
   });
   

Configuration Quirks

• Environment-Specific Ignores Override config/draw.php per environment (e.g., config/draw-local.php):

  'ignored_annotations' => env('DRAW_IGNORED_ANNOTATIONS', []),
  

• Namespacing Ensure ignored annotations use fully qualified class names (e.g., \App\Annotations\Route instead of Route).

• Performance Avoid ignoring too many annotations, as each ignored annotation adds a small overhead to the AnnotationReader.