Laravel Structure Kit Laravel Package

Getting Started

To begin leveraging Laravel Structure Kit in your daily workflow, follow these minimal steps:

1. Installation:

   composer require mehedi250/laravel-structure-kit
   

   No additional configuration is required due to Laravel’s auto-discovery.

2. First Use Case:

   • Access the UI panel at http://localhost:8000/structure-kit in your browser.
   • Enter a model name (e.g., Product).
   • Select the components you need (e.g., Model, Controller, Service Pattern, Repository Pattern).
   • Click Generate Files to scaffold the entire structure in one click.

   For CLI users, run:

   php artisan structure-kit Product mcsr
   

   This generates a Model, Controller, Service, and Repository for Product.

Implementation Patterns

Daily Workflow Integration

1. Feature Development:

   • Start with the UI to scaffold the Model, Migration, and Service/Repository layers before writing any business logic.
   • Use the live preview to validate the structure before generation.

2. Team Onboarding:

   • Standardize project structure by configuring default paths in the UI (e.g., app/Services/Implementations).
   • Use the "Remember current path" option to maintain consistency across the team.

3. Refactoring:

   • Generate Service/Repository layers for existing Models to introduce clean architecture incrementally.
   • Example:

     php artisan structure-kit User s --dry-run
     

     Preview the Service layer before applying it to production code.

4. Migration Management:

   • Always generate Migrations alongside Models to ensure database consistency.
   • Customize the migration table name in the UI if needed.

5. Testing:

   • Use the generated Interfaces (*ServiceInterface.php, *RepositoryInterface.php) to mock dependencies in unit tests.
   • Example test structure:

     public function test_product_service_creates_product()
     {
         $mockRepo = Mockery::mock(ProductRepositoryInterface::class);
         $service = new ProductService($mockRepo);
         // ...
     }
     

CLI vs. UI Tradeoffs

Integration with Laravel Ecosystem

• Laravel Breeze/Jetstream: Scaffold User-related Services/Repositories for authentication logic.

  php artisan structure-kit User mcsr
  

• Laravel Scout: Generate a Service layer for search functionality.

  php artisan structure-kit Product s --namespace="App\Services\Search"
  

• Laravel Nova: Use the generated Controllers as a base for Nova resources.

Gotchas and Tips

Pitfalls

1. Namespace Collisions:

   • If you customize paths (e.g., app/Services/Custom), ensure the namespace in the generated file matches the directory.
   • Fix: Use the --namespace flag in CLI or manually edit the namespace line in the UI preview.

2. Migration Conflicts:

   • Generating a Migration for an existing table will overwrite the file.
   • Fix: Use --dry-run to preview or manually merge migrations.

3. Service/Repository Overrides:

   • If you regenerate a Service/Repository, the package won’t overwrite existing implementations by default.
   • Fix: Delete the old file or use --force (if available in future versions).

4. PHP Version Mismatch:

   • The package requires PHP 8.1+. Older versions may cause syntax errors in generated files.
   • Fix: Update PHP or use a compatible Laravel version.

5. UI Caching:

   • The UI may cache paths between sessions if "Remember current path" is enabled.
   • Fix: Clear browser cache or use Incognito mode for testing.

Debugging Tips

• Check Generated Files: Use git diff to compare changes before committing:

  git diff --name-only
  

• CLI Verbosity: Add -v for detailed output:

  php artisan structure-kit Product mcsr -v
  

• Log Errors: Enable Laravel’s debug mode in .env:

  APP_DEBUG=true
  

Extension Points

1. Custom Templates:

   • Override the default templates by publishing the package’s views:

     php artisan vendor:publish --tag=structure-kit-views
     

   • Modify resources/views/vendor/structure-kit/ to change generated file stubs.

2. Additional Flags:

   • Extend the CLI with custom flags (e.g., --with-tests) by modifying the GenerateCommand class in the package’s source.

3. Event Listeners:

   • Listen to the structure-kit.generated event to post-process files:

     use Mehedi250\StructureKit\Events\FilesGenerated;
     
     public function handle(FilesGenerated $event)
     {
         // Add custom logic, e.g., run migrations or seed data
     }
     

Performance Quirks

• Large Projects: Generating files for deeply nested structures (e.g., app/Domain/User/Services/) may slow down the UI. Workaround: Use CLI for bulk operations.
• File Permissions: Ensure the Laravel storage directory (storage/) and bootstrap/cache/ are writable:

  chmod -R 775 storage bootstrap/cache
  

Pro Tips

• Pair with Laravel Forge: Automate scaffolding in deployment scripts:

  # In a Forge deployment hook
  php artisan structure-kit User mcsr --namespace="App\Modules\User"
  

• Combine with Laravel IDE Helper: Generate PHPStorm metadata for autocompletion:

  php artisan structure-kit Product mcsr && php artisan ide-helper:generate
  

• Document Your Structure: Add a STRUCTURE.md file in your repo to explain the conventions enforced by the package:

  ## Project Structure
  - All Services must implement `App\Services\Contracts\*Interface`.
  - Repositories live in `app/Repositories/Eloquent/` and extend `BaseRepository`.