{"id":31920231,"url":"https://github.com/iamgerwin/laravel-api-scaffold","last_synced_at":"2026-01-20T16:35:10.945Z","repository":{"id":318524757,"uuid":"1071653562","full_name":"iamgerwin/laravel-api-scaffold","owner":"iamgerwin","description":"Laravel API Scaffold automates the creation of service-oriented architecture components in your Laravel application. It generates well-structured service classes with interfaces, controllers with dependency injection, form requests, API resources, and best practices.","archived":false,"fork":false,"pushed_at":"2025-10-07T17:44:41.000Z","size":31,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-07T18:42:39.021Z","etag":null,"topics":["api","design-pattern","laravel","service-layer"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iamgerwin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-07T16:23:59.000Z","updated_at":"2025-10-07T17:44:45.000Z","dependencies_parsed_at":"2025-10-07T18:42:46.322Z","dependency_job_id":null,"html_url":"https://github.com/iamgerwin/laravel-api-scaffold","commit_stats":null,"previous_names":["iamgerwin/laravel-api-scaffold"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/iamgerwin/laravel-api-scaffold","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamgerwin%2Flaravel-api-scaffold","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamgerwin%2Flaravel-api-scaffold/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamgerwin%2Flaravel-api-scaffold/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamgerwin%2Flaravel-api-scaffold/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iamgerwin","download_url":"https://codeload.github.com/iamgerwin/laravel-api-scaffold/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamgerwin%2Flaravel-api-scaffold/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279003899,"owners_count":26083640,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","design-pattern","laravel","service-layer"],"created_at":"2025-10-13T21:56:35.082Z","updated_at":"2025-10-13T21:56:37.269Z","avatar_url":"https://github.com/iamgerwin.png","language":"PHP","readme":"# Laravel API Scaffold\n\nA comprehensive Laravel package that scaffolds Service layer architecture with API resources, controllers, and tests. This package follows best practices and provides a battle-tested structure for building maintainable Laravel applications.\n\n## Description\n\nLaravel API Scaffold automates the creation of service-oriented architecture components in your Laravel application. It generates well-structured service classes with interfaces, controllers with dependency injection, form requests, API resources, and comprehensive tests, all following Laravel conventions and best practices.\n\n## Features\n\n- 🏗️ **Service Layer Architecture**: Automatically generates service classes with their interfaces\n- 🔌 **Dependency Injection**: Auto-registers service bindings in AppServiceProvider\n- 🎯 **Complete API Scaffolding**: Creates Models, Migrations, Controllers, Requests, and Resources\n- 🚀 **Laravel 11+ API Setup**: Automatically runs `php artisan install:api` for Laravel 11+ projects\n- 🛣️ **Interactive Route Management**: Choose to append routes to api.php or create separate route files\n- 🎛️ **Admin Panel Integration**: Generate Laravel Nova or Filament resources with auto-detection\n- 📝 **Entity Documentation**: Auto-generate comprehensive markdown documentation for each entity\n- 🧪 **Testing Ready**: Generates Pest/PHPUnit test files with common test cases\n- ⚙️ **Highly Configurable**: Customize paths, namespaces, and generation options\n- 🔒 **Safe Operations**: Automatic backups of existing files before modifications\n- 📦 **Modular Approach**: Generate only what you need with granular options\n- 🎨 **Custom Stubs**: Publish and customize stub templates to match your coding style\n\n## Requirements\n\n- PHP 8.1, 8.2, 8.3, or 8.4\n- Laravel 10.x, 11.x, or 12.x\n- Composer\n\n## Installation\n\nYou can install the package via composer:\n\n```bash\ncomposer require iamgerwin/laravel-api-scaffold\n```\n\n### Publish Configuration (Optional)\n\nPublish the configuration file to customize the package behavior:\n\n```bash\nphp artisan vendor:publish --tag=\"api-scaffold-config\"\n```\n\n### Publish Stubs (Optional)\n\nPublish the stub templates if you want to customize the generated files:\n\n```bash\nphp artisan vendor:publish --tag=\"api-scaffold-stubs\"\n```\n\n## Usage\n\n### Interactive Mode (New!)\n\nThe package now features an intuitive interactive mode that guides you through the scaffolding process. When you run the command without any flags, it automatically launches an interactive wizard:\n\n```bash\nphp artisan make:service-api Product\n```\n\nThe interactive wizard will:\n1. **Preset Selection**: Choose from predefined templates (Minimal, API Complete, Service Layer, or Custom)\n2. **Component Selection**: Select which components to generate\n3. **Preview \u0026 Confirm**: Review your selections before generating files\n4. **Cache Preferences**: Remember your choices for next time\n\n#### Available Presets\n\n- **Minimal**: Service and Interface only\n- **API Complete**: Full API scaffold with all components (Service, Interface, Model, Migration, Controller, Request, Resource, Tests)\n- **Service Layer**: Service, Interface, Model, and Tests (great for business logic-heavy applications)\n- **Custom**: Choose components individually\n\n#### Interactive Mode Options\n\n```bash\n# Force interactive mode (even with flags)\nphp artisan make:service-api Product --interactive\n\n# Disable interactive mode (use flags instead)\nphp artisan make:service-api Product --no-interactive --all\n```\n\n### Automatic Laravel 11+ API Setup\n\nWhen using Laravel 11 or higher, the package automatically detects if your project needs API scaffolding:\n\n- **Auto-detection**: Checks if `routes/api.php` exists\n- **Auto-installation**: Runs `php artisan install:api` if needed\n- **Seamless setup**: Installs Laravel Sanctum and sets up API routes automatically\n\nThis ensures your Laravel 11+ project is properly configured for API development without manual intervention.\n\n### Interactive Route Management\n\nAfter generating a controller, the package offers an interactive prompt to add routes for your new resource:\n\n```bash\nWould you like to add API routes for this resource? (yes/no)\n```\n\nYou can choose between two route management strategies:\n\n#### Option 1: Append to routes/api.php\nRoutes are added directly to your main API routes file:\n\n```php\n// Product API Routes\nRoute::apiResource('products', ProductController::class);\n```\n\n**Best for:**\n- Small to medium projects\n- Quick prototyping\n- Simple API structures\n\n#### Option 2: Create separate route file\nCreates a dedicated route file at `routes/api/{model}.php`:\n\n```php\n\u003c?php\n\nuse App\\Http\\Controllers\\ProductController;\nuse Illuminate\\Support\\Facades\\Route;\n\n// Product API Routes\nRoute::apiResource('products', ProductController::class);\n```\n\nAnd automatically includes it in `routes/api.php`:\n\n```php\nrequire __DIR__.'/api/product.php';\n```\n\n**Best for:**\n- Large projects with many resources\n- Better organization and separation of concerns\n- Team collaboration (reduces merge conflicts)\n- Modular API design\n\n### Basic Usage\n\nGenerate a service with its interface (non-interactive):\n\n```bash\nphp artisan make:service-api Comment --no-interactive\n```\n\nThis creates:\n- `app/Services/Comment/CommentService.php`\n- `app/Services/Comment/CommentServiceInterface.php`\n- Automatically registers the binding in `AppServiceProvider`\n\n### Generate with API Methods\n\nCreate a service with predefined CRUD methods:\n\n```bash\nphp artisan make:service-api Comment --api\n```\n\nThis generates a service with the following methods:\n- `index()` - Get paginated list\n- `show($id)` - Get single record\n- `store(array $data)` - Create new record\n- `update($id, array $data)` - Update existing record\n- `destroy($id)` - Delete record\n\n### Generate All Related Files\n\nCreate a complete API resource with one command:\n\n```bash\nphp artisan make:service-api Comment --all\n```\n\nThis generates:\n- Service and Interface\n- Model\n- Migration\n- Controller (with service injection)\n- Form Request\n- API Resource\n- Feature Test\n\n### Granular Control\n\nGenerate only specific components:\n\n```bash\n# Service with controller and request only\nphp artisan make:service-api Comment --controller --request\n\n# Service with model and migration only\nphp artisan make:service-api Comment --model --migration\n\n# Service with API methods and tests\nphp artisan make:service-api Comment --api --test\n```\n\n### Force Overwrite\n\nOverwrite existing files (creates backups automatically):\n\n```bash\nphp artisan make:service-api Comment --force\n```\n\n### Admin Panel Integration\n\nGenerate admin panel resources for Laravel Nova or Filament:\n\n```bash\n# Generate Nova resource\nphp artisan make:service-api Product --nova\n\n# Generate Filament resource\nphp artisan make:service-api Product --filament\n\n# Auto-detect and generate for available admin panel\nphp artisan make:service-api Product --admin\n```\n\nThe package automatically detects which admin panel is installed (Nova or Filament) and generates the appropriate resource files. The `--admin` flag will use the configured default admin panel or prompt you to choose if both are installed.\n\n**Generated Nova Resource:**\n- `app/Nova/Product.php` - Nova resource with basic field configuration\n\n**Generated Filament Resources:**\n- `app/Filament/Resources/ProductResource.php` - Main resource file\n- `app/Filament/Resources/ProductResource/Pages/ListProduct.php` - List page\n- `app/Filament/Resources/ProductResource/Pages/CreateProduct.php` - Create page\n- `app/Filament/Resources/ProductResource/Pages/EditProduct.php` - Edit page\n\n### Entity Documentation\n\nAuto-generate comprehensive markdown documentation for your entities:\n\n```bash\nphp artisan make:service-api Product --docs\n```\n\nThis creates `docs/entities/Product.md` with:\n- Model overview and database schema\n- Relationships documentation\n- API endpoint documentation\n- Service layer documentation\n- Admin panel integration details\n- Validation rules documentation\n\n## Configuration\n\nThe configuration file allows you to customize various aspects of the package:\n\n```php\nreturn [\n    // Where service files will be generated\n    'service_path' =\u003e app_path('Services'),\n\n    // Which files to generate by default\n    'generate' =\u003e [\n        'model' =\u003e true,\n        'migration' =\u003e true,\n        'controller' =\u003e true,\n        'request' =\u003e true,\n        'resource' =\u003e true,\n        'interface' =\u003e true,\n        'tests' =\u003e true,\n    ],\n\n    // Backup existing files before modification\n    'backup_existing' =\u003e true,\n\n    // Auto-register service bindings\n    'auto_register_bindings' =\u003e true,\n\n    // Path to AppServiceProvider\n    'provider_path' =\u003e app_path('Providers/AppServiceProvider.php'),\n\n    // Default API methods when using --api flag\n    'api_methods' =\u003e [\n        'index',\n        'show',\n        'store',\n        'update',\n        'destroy',\n    ],\n\n    // Use custom published stubs\n    'use_custom_stubs' =\u003e false,\n\n    // Namespace configuration\n    'namespaces' =\u003e [\n        'service' =\u003e 'App\\\\Services',\n        'controller' =\u003e 'App\\\\Http\\\\Controllers',\n        'request' =\u003e 'App\\\\Http\\\\Requests',\n        'resource' =\u003e 'App\\\\Http\\\\Resources',\n        'model' =\u003e 'App\\\\Models',\n    ],\n\n    // Interactive mode enabled by default\n    'interactive_mode' =\u003e true,\n\n    // Preset configurations for interactive mode\n    'presets' =\u003e [\n        'minimal' =\u003e [\n            'name' =\u003e 'Minimal',\n            'description' =\u003e 'Service and Interface only',\n            'options' =\u003e [...],\n        ],\n        'api-complete' =\u003e [\n            'name' =\u003e 'API Complete',\n            'description' =\u003e 'Full API scaffold with all components',\n            'options' =\u003e [...],\n        ],\n        'service-layer' =\u003e [\n            'name' =\u003e 'Service Layer',\n            'description' =\u003e 'Service, Interface, Model, and Tests',\n            'options' =\u003e [...],\n        ],\n        'custom' =\u003e [\n            'name' =\u003e 'Custom',\n            'description' =\u003e 'Choose components individually',\n            'options' =\u003e [],\n        ],\n    ],\n\n    // Cache user preferences for faster subsequent use\n    'cache_preferences' =\u003e true,\n\n    // Path where preferences will be cached\n    'preferences_cache_path' =\u003e storage_path('app/api-scaffold-preferences.json'),\n];\n```\n\n## Generated File Structure\n\nWhen running `php artisan make:service-api Comment --all`, the following structure is created:\n\n```\napp/\n├── Services/\n│   └── Comment/\n│       ├── CommentService.php\n│       └── CommentServiceInterface.php\n├── Http/\n│   ├── Controllers/\n│   │   └── CommentController.php\n│   ├── Requests/\n│   │   └── CommentRequest.php\n│   └── Resources/\n│       └── CommentResource.php\n├── Models/\n│   └── Comment.php\n└── Providers/\n    └── AppServiceProvider.php (automatically updated)\n\ndatabase/\n└── migrations/\n    └── xxxx_xx_xx_create_comments_table.php\n\ntests/\n└── Feature/\n    └── CommentTest.php\n```\n\n## Example Controller\n\nThe generated controller automatically injects the service interface:\n\n```php\n\u003c?php\n\nnamespace App\\Http\\Controllers;\n\nuse App\\Services\\Comment\\CommentServiceInterface;\nuse App\\Http\\Requests\\CommentRequest;\nuse App\\Http\\Resources\\CommentResource;\n\nclass CommentController extends Controller\n{\n    public function __construct(\n        protected CommentServiceInterface $commentService\n    ) {\n    }\n\n    public function index()\n    {\n        $data = $this-\u003ecommentService-\u003eindex();\n        return CommentResource::collection($data);\n    }\n\n    public function show(int $id)\n    {\n        $data = $this-\u003ecommentService-\u003eshow($id);\n\n        if (!$data) {\n            return response()-\u003ejson(['message' =\u003e 'Comment not found'], 404);\n        }\n\n        return response()-\u003ejson(new CommentResource($data));\n    }\n\n    // ... other methods\n}\n```\n\n## Architecture Flow\n\nThis package implements a clean Service Layer Architecture pattern. Here's how the request flows through the application:\n\n```mermaid\nsequenceDiagram\n    participant Client\n    participant Route\n    participant Controller\n    participant Service\n    participant Model\n    participant Database\n\n    Client-\u003e\u003eRoute: HTTP Request (POST /api/comments)\n    Route-\u003e\u003eController: Route to CommentController@store\n    Controller-\u003e\u003eController: Validate via CommentRequest\n    Controller-\u003e\u003eService: $commentService-\u003estore($data)\n    Service-\u003e\u003eService: Business Logic Processing\n    Service-\u003e\u003eModel: Comment::create($data)\n    Model-\u003e\u003eDatabase: INSERT query\n    Database--\u003e\u003eModel: Record created\n    Model--\u003e\u003eService: Comment instance\n    Service--\u003e\u003eController: Comment instance\n    Controller-\u003e\u003eController: Transform via CommentResource\n    Controller--\u003e\u003eClient: JSON Response (201)\n```\n\n### Flow Explanation\n\n1. **Client Request**: The client sends an HTTP request to your Laravel application\n2. **Routing**: Laravel routes the request to the appropriate controller method\n3. **Validation**: The FormRequest validates incoming data automatically\n4. **Service Layer**: The controller delegates business logic to the service\n5. **Business Logic**: The service processes the request (calculations, validations, etc.)\n6. **Data Persistence**: The service uses the model to interact with the database\n7. **Response Transformation**: The controller transforms the data using API Resources\n8. **Client Response**: A formatted JSON response is returned to the client\n\n### Benefits of This Architecture\n\n- **Separation of Concerns**: Controllers handle HTTP, Services handle business logic\n- **Testability**: Services can be tested independently of HTTP layer\n- **Reusability**: Services can be used across multiple controllers or commands\n- **Maintainability**: Business logic is centralized and easier to modify\n- **Dependency Injection**: Interfaces allow for easy mocking and testing\n\n## Edge Cases and Advanced Usage\n\n### Working with Existing Files\n\nThe package intelligently handles existing files:\n\n1. **Without --force flag**: Skips existing files and warns you\n2. **With --force flag**: Creates timestamped backups before overwriting\n\n```bash\n# This will backup existing files with .backup.YmdHis extension\nphp artisan make:service-api Comment --force\n```\n\n### Custom Service Paths\n\nOverride the default service path in your configuration:\n\n```php\n'service_path' =\u003e base_path('src/Services'),\n```\n\n### Disabling Auto-Registration\n\nIf you prefer manual service registration:\n\n```php\n'auto_register_bindings' =\u003e false,\n```\n\nThen manually register in your `AppServiceProvider`:\n\n```php\nuse App\\Services\\Comment\\CommentServiceInterface;\nuse App\\Services\\Comment\\CommentService;\n\npublic function register(): void\n{\n    $this-\u003eapp-\u003ebind(CommentServiceInterface::class, CommentService::class);\n}\n```\n\n### Multi-Word Service Names\n\nThe package handles camelCase and PascalCase correctly:\n\n```bash\nphp artisan make:service-api BlogPost --all\n# Creates: BlogPostService, BlogPostController, etc.\n\nphp artisan make:service-api UserProfile --all\n# Creates: UserProfileService, UserProfileController, etc.\n```\n\n### Nested Services\n\nCreate nested service structures:\n\n```bash\n# The service name can include subdirectories\nphp artisan make:service-api Blog/Post --all\n```\n\nThis creates:\n```\napp/Services/\n└── Blog/\n    └── Post/\n        ├── PostService.php\n        └── PostServiceInterface.php\n```\n\n## Testing\n\nRun the package tests:\n\n```bash\ncomposer test\n```\n\nRun tests with coverage:\n\n```bash\ncomposer test-coverage\n```\n\nRun static analysis:\n\n```bash\ncomposer analyse\n```\n\nFormat code:\n\n```bash\ncomposer format\n```\n\n## Code Quality\n\nThis package maintains high code quality standards:\n\n- **PHPStan Level 5**: Static analysis for type safety\n- **Laravel Pint**: Code style formatting\n- **Pest/PHPUnit**: Comprehensive test coverage\n- **GitHub Actions**: Automated CI/CD pipeline\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING](CONTRIBUTING.md) for details.\n\n### Reporting Issues\n\nIf you encounter a bug or have a feature request, please submit an issue on GitHub:\n\n**Issue Submission Guidelines:**\n\n1. **Visit**: [https://github.com/iamgerwin/laravel-api-scaffold/issues](https://github.com/iamgerwin/laravel-api-scaffold/issues)\n2. **Search First**: Check if your issue already exists before creating a new one\n3. **Provide Details**: Include the following information:\n   - Clear and descriptive title\n   - Laravel version and PHP version\n   - Package version\n   - Steps to reproduce the issue\n   - Expected behavior vs actual behavior\n   - Error messages or stack traces (if applicable)\n   - Screenshots or screen recordings (highly appreciated)\n   - Code samples demonstrating the issue\n\n**Example Issue Format:**\n```\n**Environment:**\n- Laravel: 11.x\n- PHP: 8.3\n- Package: 0.3.3\n\n**Steps to Reproduce:**\n1. Run `php artisan make:service-api Post --all`\n2. Notice that...\n\n**Expected Behavior:**\nShould generate...\n\n**Actual Behavior:**\nInstead, it generates...\n\n**Screenshots:**\n[Attach screenshot or recording]\n```\n\n### Development Setup\n\n1. Clone the repository\n2. Install dependencies: `composer install`\n3. Run tests: `composer test`\n4. Submit a pull request\n\n## Security Vulnerabilities\n\nIf you discover a security vulnerability within Laravel API Scaffold, please send an email to [iamgerwin@live.com](mailto:iamgerwin@live.com). All security vulnerabilities will be promptly addressed.\n\n## Roadmap\n\n- [ ] Support for custom service method templates\n- [x] Interactive mode for selecting which files to generate\n- [ ] Support for API versioning structure\n- [ ] Repository pattern option\n- [ ] GraphQL support\n- [ ] OpenAPI/Swagger documentation generation\n- [ ] Service layer documentation generator\n- [ ] Event and listener scaffolding\n- [ ] Job/Queue scaffolding integration\n\n## Credits\n\n- [Gerwin](https://github.com/iamgerwin)\n- Inspired by [Spatie's Package Skeleton](https://github.com/spatie/package-skeleton-laravel)\n- All [Contributors](../../contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamgerwin%2Flaravel-api-scaffold","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiamgerwin%2Flaravel-api-scaffold","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamgerwin%2Flaravel-api-scaffold/lists"}