Appframe Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require milestone/appframe
   

   Publish the package assets and config:

   php artisan vendor:publish --provider="Milestone\Appframe\AppframeServiceProvider"
   

2. Basic Usage

   • Generate a new Appframe CRUD module (if supported):

     php artisan appframe:module ModuleName
     

   • If no CLI generator exists, manually scaffold a module in app/Modules/ModuleName with:
     • ModuleNameServiceProvider.php
     • ModuleNameController.php
     • ModuleNameModel.php (extending Appframe\Model)
     • ModuleNameView (Blade templates in resources/views/modules/module-name/)

3. First Use Case

   • Define a model (e.g., User):

     namespace App\Modules\Users\Models;
     
     use Milestone\Appframe\Model;
     
     class User extends Model
     {
         protected $fillable = ['name', 'email'];
     }
     

   • Register the module in config/appframe.php:

     'modules' => [
         'users' => [
             'namespace' => 'App\Modules\Users',
             'controller' => 'UsersController',
             'model' => 'User',
         ],
     ],
     

   • Access the module via a route (e.g., routes/web.php):

     Route::module('users', 'App\Modules\Users\Http\Controllers\UsersController');
     

Implementation Patterns

Core Workflows

1. CRUD Operations

   • Leverage built-in methods for common actions:

     // In a controller
     $users = \Appframe::module('users')->all(); // Fetches all records
     $user = \Appframe::module('users')->find(1); // Single record
     $created = \Appframe::module('users')->create($request->all()); // Create
     \Appframe::module('users')->update(1, $request->all()); // Update
     \Appframe::module('users')->delete(1); // Delete
     

2. Module Registration

   • Dynamically register modules in AppframeServiceProvider:

     public function registerModules()
     {
         \Appframe::registerModule('users', [
             'namespace' => 'App\Modules\Users',
             'controller' => 'UsersController',
             'model' => 'User',
             'views' => 'modules.users',
         ]);
     }
     

3. View Integration

   • Use Blade directives for module-specific layouts:

     @moduleLayout('users')
         @moduleContent('users.index')
     @endmoduleLayout
     

   • Extend base views in resources/views/modules/_layouts/base.blade.php.

4. Middleware & Policies

   • Attach module-specific middleware:

     \Appframe::module('users')->middleware('auth');
     

   • Define policies in ModuleNamePolicy.php:

     public function before($request)
     {
         if ($request->user()->cannot('manage-users')) {
             abort(403);
         }
     }
     

5. API Endpoints

   • Enable API mode for a module:

     \Appframe::module('users')->api(true);
     

   • Use Resource classes for API responses:

     namespace App\Modules\Users\Http\Resources;
     
     use Milestone\Appframe\Http\Resources\JsonResource;
     
     class UserResource extends JsonResource
     {
         public function toArray($request)
         {
             return [
                 'id' => $this->id,
                 'name' => $this->name,
             ];
         }
     }
     

Integration Tips

• Laravel Mix/Webpack: Configure module-specific assets in webpack.mix.js:

  mix.js('resources/js/modules/users/app.js', 'public/js/modules/users')
       .sass('resources/sass/modules/users/app.scss', 'public/css/modules/users');
  

• Database Migrations: Use module-specific migrations in database/migrations/module_name_*_create_*_table.php.
• Testing: Mock modules in PHPUnit:

  $module = \Mockery::mock('overload:\Milestone\Appframe\Facades\Appframe');
  $module->shouldReceive('module')->andReturn($mockModule);
  

Gotchas and Tips

Pitfalls

1. Namespace Conflicts

   • Ensure module namespaces in config/appframe.php match the actual directory structure. Example:

     app/Modules/Users/Models/User.php → 'namespace' => 'App\Modules\Users\Models'
     

   • Fix: Double-check autoloading with composer dump-autoload.

2. Outdated CLI Tools

   • The package lacks a CLI generator (as of 2020). Manually scaffold modules or extend the package’s AppframeCommand class.

3. Laravel Version Compatibility

   • Tested with Laravel 5.x. For Laravel 8/9:
     • Override service providers to use registerModuleBinding() instead of bind().
     • Update Blade directives if syntax changes (e.g., @moduleLayout may conflict with newer Laravel directives).

4. Caching Issues

   • Clear module routes/cache after changes:

     php artisan route:clear
     php artisan config:clear
     

5. Model Binding

   • Ensure Appframe\Model extends Laravel’s Model correctly. If not, override the resolveRouteKey() method:

     public function resolveRouteKey()
     {
         return $this->id;
     }
     

Debugging Tips

1. Module Not Found

   • Verify the module is registered in config/appframe.php and the service provider is loaded in config/app.php:

     'providers' => [
         Milestone\Appframe\AppframeServiceProvider::class,
     ],
     

2. Route Errors

   • Check if the module’s controller is properly bound:

     \Appframe::module('users')->controller(); // Should return the controller instance
     

   • Debug routes with:

     php artisan route:list
     

3. View Not Loading

   • Ensure the views path in config/appframe.php is correct and the Blade file exists at resources/views/modules/module-name/view-name.blade.php.

4. Database Queries

   • Use Laravel’s query logging:

     \DB::enableQueryLog();
     $users = \Appframe::module('users')->all();
     dd(\DB::getQueryLog());
     

Extension Points

1. Custom Directives Extend Blade directives in AppframeServiceProvider:

   Blade::directive('moduleContent', function ($expression) {
       return "<?php echo \Appframe::moduleContent($expression); ?>";
   });
   

2. Event Listeners Listen to module events (e.g., module.created):

   \Appframe::module('users')->on('created', function ($model) {
       // Post-create logic
   });
   

3. API Resources Override default JSON responses by extending Milestone\Appframe\Http\Resources\JsonResource.

4. Validation Rules Add module-specific rules in ModuleNameRules.php:

   namespace App\Modules\Users\Rules;
   
   use Milestone\Appframe\Rules\AbstractRules;
   
   class UserRules extends AbstractRules
   {
       public function rules()
       {
           return [
               'email' => 'required|email|unique:users',
           ];
       }
   }
   

   Attach to the module:

   \Appframe::module('users')->rules(new UserRules());
   

5. Localization Override translations in resources/lang/en/module-name.php:

   return [
       'create' => 'New User',
       'edit' => 'Edit User',
   ];