Org Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dwi-rengga/org
   

   Publish the migration and config (if available):

   php artisan vendor:publish --provider="DwiRengga\Org\OrgServiceProvider"
   

   Run migrations:

   php artisan migrate
   

2. First Use Case: Define an Organization Register the organization model and seed initial data:

   use DwiRengga\Org\Models\Organization;
   
   // Create a new org
   $org = Organization::create([
       'name' => 'Acme Corp',
       'slug' => 'acme',
       'description' => 'Global leader in widgets',
   ]);
   

3. Key Files to Review

   • config/org.php (if published)
   • app/Models/Organization.php (or vendor/dwi-rengga/org/src/Models/Organization.php)
   • database/migrations/ for schema details

Implementation Patterns

Core Workflows

1. Hierarchical Structure Management Use the hasMany/belongsTo relationships for departments, teams, or roles:

   // Define relationships in Organization model
   public function departments()
   {
       return $this->hasMany(Department::class);
   }
   
   // Create a department under an org
   $org->departments()->create(['name' => 'Engineering']);
   

2. User-Organization Assignment Extend the User model to link to organizations:

   // In User model
   public function organizations()
   {
       return $this->belongsToMany(Organization::class, 'user_organization');
   }
   
   // Assign a user to an org
   $user->organizations()->attach($org->id, ['role' => 'admin']);
   

3. API Resource Integration Generate a resource for RESTful endpoints:

   php artisan make:resource OrgResource --model=DwiRengga\Org\Models\Organization
   

   Customize fields in OrgResource:

   public function toArray($request)
   {
       return [
           'id' => $this->id,
           'name' => $this->name,
           'departments_count' => $this->departments()->count(),
       ];
   }
   

4. Policy-Based Access Control Create policies for org-specific permissions:

   php artisan make:policy OrgPolicy --model=Organization
   

   Example:

   public function viewAny(User $user)
   {
       return $user->hasRole(['admin', 'manager']);
   }
   

Integration Tips

• Laravel Nova/Panel: Publish the package’s Nova tools (if available) via:

  php artisan vendor:publish --tag=org-nova
  

• Scopes: Add custom scopes for filtering:

  public function scopeActive($query)
  {
      return $query->where('status', 'active');
  }
  

• Observers: Track org changes (e.g., audit logs):

  Organization::observe(OrgObserver::class);
  

Gotchas and Tips

Pitfalls

1. Missing Middleware Ensure org middleware is registered in app/Http/Kernel.php if using route groups:

   'org' => \DwiRengga\Org\Http\Middleware\OrgMiddleware::class,
   

   Usage:

   Route::middleware(['org'])->group(function () {
       // Org-specific routes
   });
   

2. Slug Conflicts Validate slugs during creation to avoid duplicates:

   $validated = $request->validate([
       'slug' => 'required|unique:organizations,slug',
   ]);
   

3. Caching Quirks Clear caches after schema changes:

   php artisan cache:clear
   php artisan config:clear
   

Debugging

• Query Logging: Enable debug mode to inspect queries:

  DEBUG=true
  

• Model Events: Use registerModelEvent for debugging:

  Organization::registerModelEvent(
      'saving',
      function ($org) {
          \Log::debug('Saving org:', [$org->toArray()]);
      }
  );
  

Extension Points

1. Custom Fields Extend the Organization model with traits or add columns via migrations:

   Schema::table('organizations', function (Blueprint $table) {
       $table->string('industry')->nullable();
   });
   

2. Event Listeners Subscribe to org events (e.g., OrgCreated):

   public function handle(OrgCreated $event)
   {
       // Send welcome email
   }
   

3. Testing Use factories for testing:

   $org = Organization::factory()->create();
   

   Or seed test data:

   $this->seedOrganizations();
   

Pro Tips

• Soft Deletes: Enable if needed:

  use Illuminate\Database\Eloquent\SoftDeletes;
  
  class Organization extends Model
  {
      use SoftDeletes;
      protected $dates = ['deleted_at'];
  }
  

• API Rate Limiting: Apply to org endpoints:

  Route::middleware(['throttle:60,1'])->group(...);
  

• Localization: Support multiple languages via localization package integration.