Planet Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Since the bundle is not yet mature, verify its compatibility with your Laravel version (if applicable) and install via Composer:

   composer require desarrolla2/planet-bundle
   

   Note: If this is a Symfony bundle, ensure you’ve added it to config/bundles.php in a Symfony/Laravel-Symfony hybrid project.

2. Publish Configuration If the bundle includes default config (even if undocumented), publish it:

   php artisan vendor:publish --provider="Desarrolla2\PlanetBundle\PlanetBundleServiceProvider"
   

   Check config/planet.php for available settings (if generated).

3. First Use Case: Basic Planet Feature The README lacks examples, but assume the bundle provides:

   • Planet data models (e.g., Planet, Galaxy).
   • API routes (e.g., /api/planets).
   • Twig/Symfony templates (if Symfony-based). Test the default route or model interactions:

   // Example: Fetch planets (if CRUD is exposed)
   $planets = \App\Models\Planet::all(); // Hypothetical; verify namespace.
   

4. Documentation Gaps

   • Fallback: Inspect the bundle’s src/ directory for:
     • PlanetBundleServiceProvider.php (boot/register methods).
     • Resources/config/ (YAML/XML config).
     • Entity/ (Doctrine models, if ORM-based).
   • Contact: Reach out to @desarrolla2 for undocumented features.

Implementation Patterns

Common Workflows

1. Model Integration

   • Extend Existing Models: If the bundle provides a Planet entity, extend it in Laravel:

     class CustomPlanet extends \Desarrolla2\PlanetBundle\Entity\Planet {
         // Add custom fields/methods
     }
     

   • Polymorphic Relations: Link planets to user-generated content (e.g., User::morphToMany(Planet::class)).

2. API Resource

   • Laravel API Resources: Create a resource to format planet responses:

     php artisan make:resource PlanetResource
     

     // app/Http/Resources/PlanetResource.php
     public function toArray($request) {
         return [
             'name' => $this->name,
             'galaxy' => GalaxyResource::make($this->galaxy),
         ];
     }
     

   • Route Integration:

     Route::apiResource('planets', PlanetController::class)->middleware('auth:sanctum');
     

3. Frontend Integration

   • Blade Views: If the bundle includes views, override them in resources/views/vendor/planet/.

     @extends('vendor.planet.list')
     @section('extra_fields')
         <td>{{ $planet->custom_field }}</td>
     @endsection
     

   • JavaScript: Fetch planets via Axios:

     axios.get('/api/planets').then(response => {
         response.data.forEach(planet => {
             console.log(planet.name);
         });
     });
     

4. Event Listeners

   • Hook into Bundle Events: If the bundle dispatches events (e.g., PlanetCreated), listen in EventServiceProvider:

     protected $listen = [
         \Desarrolla2\PlanetBundle\Events\PlanetCreated::class => [
             \App\Listeners\LogPlanetCreation::class,
         ],
     ];
     

5. Testing

   • Unit Tests: Mock the bundle’s services:

     $this->partialMock(PlanetService::class, function ($mock) {
         $mock->shouldReceive('findAll')->andReturn([new Planet()]);
     });
     

   • Feature Tests: Test API endpoints:

     $response = $this->getJson('/api/planets');
     $response->assertStatus(200)->assertJsonStructure([['name']]);
     

Gotchas and Tips

Pitfalls

1. Undocumented Dependencies

   • Symfony vs. Laravel: The bundle may assume Symfony components (e.g., Twig, Doctrine). If using pure Laravel:
     • Replace make:entity with Laravel’s make:model.
     • Mock Symfony services in tests (e.g., ContainerInterface).
   • PHP Version: Check composer.json for required PHP version (e.g., ^8.0).

2. Namespace Conflicts

   • The bundle may use Desarrolla2\PlanetBundle\.... Avoid collisions by:
     • Aliasing in config/app.php:

       'aliases' => [
           'Planet' => Desarrolla2\PlanetBundle\Facades\Planet::class,
       ],
       

     • Using fully qualified namespaces in code.

3. Missing Migrations

   • If the bundle includes a Planet table, run:

     php artisan migrate
     

   • Tip: Check src/Resources/migrations/ for custom migrations.

4. Configuration Overrides

   • The bundle may not publish config. Hardcode defaults in config/planet.php:

     return [
         'default_galaxy' => 'Milky Way',
         'api_prefix' => 'api/v1',
     ];
     

5. Event Dispatching

   • If the bundle dispatches events silently, listen globally:

     // app/Providers/EventServiceProvider.php
     protected $listen = [
         \Desarrolla2\PlanetBundle\Events\PlanetEvent::class => [
             \App\Listeners\HandlePlanetEvent::class,
         ],
     ];
     

Debugging Tips

1. Log Bundle Output Add a listener to debug events:

   // app/Listeners/DebugPlanetEvents.php
   public function handle(PlanetEvent $event) {
       \Log::info('Planet event triggered', $event->toArray());
   }
   

2. Check Service Container Dump the bundle’s bound services:

   $services = app()->getBindings();
   dd(array_filter($services, fn($service) => str_contains($service, 'PlanetBundle')));
   

3. Override Bundle Classes Use Laravel’s binding overrides:

   $this->app->bind(
       \Desarrolla2\PlanetBundle\Services\PlanetService::class,
       \App\Services\CustomPlanetService::class
   );
   

Extension Points

1. Custom Repositories Replace the bundle’s repository:

   // config/planet.php
   'repository' => \App\Repositories\CustomPlanetRepository::class,
   

2. Add Fields to Entities Extend the Planet entity:

   namespace App\Entity;
   use Desarrolla2\PlanetBundle\Entity\Planet as BasePlanet;
   
   class Planet extends BasePlanet {
       /**
        * @ORM\Column(type="string", nullable=true)
        */
       private $customAttribute;
   }
   

3. Create Custom Commands Extend the bundle’s commands:

   namespace App\Console\Commands;
   use Desarrolla2\PlanetBundle\Console\PlanetCommand;
   
   class CustomPlanetCommand extends PlanetCommand {
       protected function getOptions() {
           return parent::getOptions() + [
               ['custom', null, InputOption::VALUE_OPTIONAL, 'Custom option'],
           ];
       }
   }
   

   Register in AppServiceProvider:

   $this->commands([
       CustomPlanetCommand::class,
   ]);
   

4. Localization Override translation files:

   cp vendor/desarrolla2/planet-bundle/resources/translations/en.json resources/lang/en/planet.json
   

Pro Tips

• Fork and Improve: Since the bundle is "not ready," fork the repo and submit PRs for:
  • Laravel-specific adapters.
  • Missing documentation (e.g., USAGE.md).
• Use php artisan package:discover: If the bundle supports discovery, add it to config/app.php:

  'providers' => [
      Desarrolla2\PlanetBundle\PlanetBundleServiceProvider::class,
  ],
  

• Monitor for Updates: Star the repo and check for updates periodically.

---
```markdown
## Final Note
Given the bundle's immaturity, treat it as a "proof of concept." Document your customizations thoroughly and consider wrapping interactions in a service layer for future compatibility.