Ship Manager Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bugover/ship-manager
   

   Publish the package config (if needed):

   php artisan vendor:publish --provider="BUGOVER\ShipManager\ShipManagerServiceProvider" --tag="config"
   

2. First Use Case: Basic Ship Creation Register a new ship via the facade (default namespace):

   use BUGOVER\ShipManager\Facades\ShipManager;
   
   $ship = ShipManager::create([
       'name' => 'USS Enterprise',
       'type' => 'starship',
       'registry' => 'NCC-1701',
       'status' => 'active',
   ]);
   

   Verify creation via Tinker or a route:

   ShipManager::find($ship->id);
   

3. Key Files to Review

   • config/ship-manager.php (default config, storage paths, etc.)
   • app/ShipManager (custom models/views if extended)
   • routes/ship-manager.php (if published)

Implementation Patterns

Core Workflows

1. CRUD Operations Use the facade for all ship-related actions:

   // Create
   ShipManager::create($data);
   
   // Read
   ShipManager::find($id);
   ShipManager::all();
   
   // Update
   ShipManager::update($id, ['status' => 'retired']);
   
   // Delete
   ShipManager::destroy($id);
   

2. Querying Ships Filter ships with fluent methods:

   $activeStarships = ShipManager::where('type', 'starship')
       ->where('status', 'active')
       ->get();
   

3. Events & Listeners Subscribe to ship lifecycle events (e.g., ShipCreated, ShipUpdated):

   // In EventServiceProvider
   protected $listen = [
       'BUGOVER\ShipManager\Events\ShipCreated' => [
           'App\Listeners\LogShipCreation',
       ],
   ];
   

4. API Integration Use the ShipResource (if included) for API responses:

   use BUGOVER\ShipManager\Http\Resources\ShipResource;
   
   return new ShipResource(ShipManager::find($id));
   

Integration Tips

• Custom Models: Extend BUGOVER\ShipManager\Models\Ship to add fields.
• Validation: Use ShipManager::validate($data) before creation.
• Storage: Override storage_path() in config for custom paths.
• Testing: Use ShipManager::factory() (if included) for seed data.

Gotchas and Tips

Common Pitfalls

1. Missing Config If ships aren’t saving, check config/ship-manager.php for storage_path or model settings.

2. Event Conflicts Ensure event namespaces match (e.g., BUGOVER\ShipManager\Events\*).

3. Facade Caching Clear cached facades after config changes:

   php artisan optimize:clear
   

4. Database Migrations If extending the ships table, run:

   php artisan migrate
   

Debugging Tips

• Log Ship Actions: Use ShipManager::logAction('create', $data) for debugging.
• Check Storage: Verify files are written to storage/app/ship-manager/ (configurable).
• Event Dumping: Temporarily dump events in listeners:

  public function handle($event) {
      \Log::debug('Ship event:', ['event' => $event]);
  }
  

Extension Points

1. Custom Fields Add fields via model casting or accessors:

   // app/Models/Ship.php
   protected $casts = ['speed' => 'float'];
   

2. Hooks Override methods in a custom service provider:

   public function boot() {
       ShipManager::extend(function ($manager) {
           $manager->macro('customMethod', function () {
               return 'Extended!';
           });
       });
   }
   

3. API Routes Publish and extend routes:

   php artisan vendor:publish --tag="ship-manager-routes"
   

   Then add custom routes in routes/ship-manager.php.