Oro Project Bundle Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation Add the bundle via Composer in your Laravel/Oro-based project:

   composer require codenetix/oro-project-bundle
   

   Register the bundle in config/app.php under the providers array:

   Codenetix\OroProjectBundle\OroProjectBundle::class,
   

2. Publish Configuration Publish the default configuration to customize behavior:

   php artisan vendor:publish --provider="Codenetix\OroProjectBundle\OroProjectServiceProvider" --tag="config"
   

   Locate the config file at config/oro_project.php.

3. First Use Case: Basic Project Management Use the bundle’s core services to create and manage projects:

   use Codenetix\OroProjectBundle\Services\ProjectManager;
   
   $projectManager = app(ProjectManager::class);
   $project = $projectManager->createProject([
       'name' => 'My New Project',
       'description' => 'A sample project',
       'status' => 'active',
   ]);
   

4. Database Migrations Run migrations to set up the required tables:

   php artisan migrate
   

Implementation Patterns

Core Workflows

1. Project CRUD Operations Leverage the ProjectManager service for seamless project lifecycle management:

   // Create
   $project = $projectManager->createProject($data);
   
   // Read
   $project = $projectManager->findProject($id);
   
   // Update
   $projectManager->updateProject($id, $updatedData);
   
   // Delete
   $projectManager->deleteProject($id);
   

2. Integration with Eloquent The bundle provides an Eloquent model (Project) for direct database interactions:

   use Codenetix\OroProjectBundle\Entity\Project;
   
   $project = Project::where('name', 'My Project')->first();
   

3. Event-Driven Extensions Subscribe to project-related events for custom logic:

   // In a service provider
   $this->app->booting(function () {
       event(new \Codenetix\OroProjectBundle\Events\ProjectCreated($project));
   });
   

4. API Resource Integration Use the bundle’s API resources to format project data for JSON responses:

   use Codenetix\OroProjectBundle\Http\Resources\ProjectResource;
   
   return new ProjectResource($project);
   

Common Integration Tips

• Validation: Use the bundle’s built-in validators for project data:

  use Codenetix\OroProjectBundle\Validators\ProjectValidator;
  
  $validator = new ProjectValidator();
  $errors = $validator->validate($data);
  

• Middleware: Protect project-related routes with middleware:

  Route::middleware(['auth', 'can:manage.projects'])->group(function () {
      Route::resource('projects', ProjectController::class);
  });
  

• Custom Fields: Extend the Project entity with additional fields via traits or inheritance.

Gotchas and Tips

Pitfalls and Debugging

1. Configuration Overrides Ensure custom configurations in oro_project.php do not conflict with default values. Use array_merge for safe overrides:

   return array_merge(require __DIR__.'/oro_project.php', [
       'default_status' => 'draft',
   ]);
   

2. Event Listener Conflicts If events fire unexpectedly, verify listener priorities in the service provider:

   $this->app->resolving(\Codenetix\OroProjectBundle\Events\ProjectCreated::class, function ($event) {
       // Custom logic here
   });
   

3. Database Schema Mismatches After updating the bundle, re-run migrations to avoid schema inconsistencies:

   php artisan migrate:fresh --env=testing
   

4. Caching Issues Clear caches after extending the bundle or modifying configurations:

   php artisan cache:clear
   php artisan config:clear
   

Extension Points

1. Custom Project Types Extend the Project entity to support custom project types:

   namespace App\Entities;
   
   use Codenetix\OroProjectBundle\Entity\Project as BaseProject;
   
   class CustomProject extends BaseProject {
       protected $customField;
   }
   

2. API Resource Customization Override the default ProjectResource to include/exclude fields:

   namespace App\Http\Resources;
   
   use Codenetix\OroProjectBundle\Http\Resources\ProjectResource as BaseResource;
   
   class CustomProjectResource extends BaseResource {
       public function toArray($request) {
           return array_merge(parent::toArray($request), [
               'custom_field' => $this->resource->customField,
           ]);
       }
   }
   

3. Validation Rules Add custom validation rules to the ProjectValidator:

   use Illuminate\Validation\Rule;
   
   $validator->addRule('name', Rule::unique('projects')->ignore($project->id));
   

4. Service Container Binding Bind custom implementations of the ProjectManager interface for testing or extended functionality:

   $this->app->bind(\Codenetix\OroProjectBundle\Services\ProjectManager::class, function ($app) {
       return new \App\Services\CustomProjectManager();
   });