Laravel Reports Laravel Package

Getting Started

Minimal Setup

1. Installation Run composer require rezaghz/laravel-reports in your project root. Publish migrations with:

   php artisan vendor:publish --provider="Rezaghz\Laravel\Reports\ReportsServiceProvider" --tag=laravel-reports-migrations
   php artisan migrate
   

2. First Use Case: Enable Reporting on a Model Extend a model (e.g., Post) to support reporting:

   use Rezaghz\Laravel\Reports\Traits\Reports;
   use Rezaghz\Laravel\Reports\Contracts\ReportsInterface;
   
   class Post extends Model implements ReportsInterface
   {
       use Reports;
       // ...
   }
   

3. Define Reportable Types In your model, specify reportable types (e.g., spam, violence):

   protected $reportableTypes = ['spam', 'violence', 'child_abuse'];
   

4. Trigger a Report In a controller or service:

   $post = Post::find(1);
   $post->report('spam'); // Reports the post as spam
   

Implementation Patterns

Core Workflows

1. Reporting a Model Instance

Use the report() method on any model implementing ReportsInterface:

$user = User::find(1);
$user->report('violence'); // Stores report in `reports` table

2. Checking Report Status

Check if a model has reports or is flagged:

if ($post->hasReports()) {
    // Handle reported content
}

3. Listing Reports

Fetch reports for a model:

$reports = $post->reports; // Collection of Report models

4. Customizing Report Behavior

Override default logic in the Reports trait:

class Post extends Model implements ReportsInterface
{
    use Reports;

    public function report($type)
    {
        // Custom logic (e.g., validate type, notify admins)
        return parent::report($type);
    }
}

Integration Tips

Validation

Validate report types before processing:

if (!in_array($type, $this->reportableTypes)) {
    throw new \InvalidArgumentException("Invalid report type.");
}

Notifications

Trigger events or notifications when reports are created:

event(new ReportCreated($report));
// Or use Laravel Notifications:
$this->notify(new AdminReportNotification($report));

API Endpoints

Create a controller to handle report submissions:

public function store(Request $request, $modelId)
{
    $model = Model::findOrFail($modelId);
    $model->report($request->type);
    return response()->json(['success' => true]);
}

Admin Dashboard

Query reports for moderation:

$reports = Report::with('reportable')->latest()->get();

Gotchas and Tips

Pitfalls

1. Missing Trait/Contract Forgetting to implement ReportsInterface or use the Reports trait will break reporting functionality. Fix: Ensure both are included in your model.

2. Unpublished Migrations Skipping vendor:publish for migrations will cause database errors. Fix: Always run migrations after publishing.

3. Report Type Mismatch Passing invalid report types (not in $reportableTypes) may silently fail or cause errors. Fix: Validate types before processing (see Validation in Integration Tips).

4. Circular Dependencies If reportable() returns a model that also uses the Reports trait, ensure no infinite loops in relationships. Fix: Use explicit foreign keys or lazy-loading.

Debugging

1. Check Database Verify reports are stored in the reports table:

   php artisan tinker
   >>> \DB::table('reports')->get();
   

2. Log Reports Add logging in the report() method to trace issues:

   \Log::debug("Reporting {$this->id} as {$type}");
   

3. Test Edge Cases Test reporting on:

   • Non-existent models (should throw ModelNotFoundException).
   • Models with no reportable types (should throw InvalidArgumentException).

Extension Points

1. Custom Report Model Extend the default Report model:

   class CustomReport extends \Rezaghz\Laravel\Reports\Models\Report
   {
       protected $table = 'custom_reports';
   }
   

   Bind it in the service provider:

   $this->app->bind(
       \Rezaghz\Laravel\Reports\Contracts\ReportModel::class,
       CustomReport::class
   );
   

2. Add Metadata Extend the report() method to store additional data:

   public function report($type, $metadata = [])
   {
       $this->reports()->create([
           'type' => $type,
           'metadata' => $metadata,
       ]);
   }
   

3. Bulk Reporting Add a method to report multiple instances:

   public static function bulkReport(array $ids, $type)
   {
       foreach ($ids as $id) {
           self::find($id)->report($type);
       }
   }
   

4. Soft-Deleting Reports Enable soft deletes in the Report model:

   use Illuminate\Database\Eloquent\SoftDeletes;
   
   class Report extends Model
   {
       use SoftDeletes;
       // ...
   }
   

Config Quirks

1. Default Report Model The package uses Rezaghz\Laravel\Reports\Models\Report by default. Override via binding (see Custom Report Model).

2. Reportable Types Ensure $reportableTypes is defined in your model or the package will default to an empty array.

3. Relationship Naming The package assumes a reports() relationship. Customize via:

   public function reports()
   {
       return $this->morphMany(\Rezaghz\Laravel\Reports\Models\Report::class, 'reportable')
                   ->where('type', 'in', $this->reportableTypes);
   }