alyakin/reporting

Flexible Laravel package for attaching user reports to any model. Useful for moderation, feedback, and auditing.

v1.0.7 2025-04-09 23:20 UTC

Requires

• php: ^8.0
• illuminate/support: ^9.0 || ^10.0 || ^11.0

Requires (Dev)

• larastan/larastan: *
• laravel/pint: *
• orchestra/testbench: *

MIT

• Alexander Lyakin

• Audit
• report
• laravel
• feedback
• moderation
• complaints
• alyakin

README

Laravel Complaint & Note Manager is a package for managing complaints, notes, and similar entities in Laravel projects. It uses polymorphic relationships for integration with any models.

Ideal for social networks, e-commerce, and content moderation projects that require collecting and managing user complaints, reports, or note (use cases).

Features:

• Polymorphic Relationships: Easy integration with different models.
• Metadata: Ability to save additional data.
• Automatic Deletion: Manage outdated records.
• Customization: Configure through configuration files and migrations.

Table of Contents

1. Laravel Complaint & Note Manager
2. Installation
   • Requirements
   • Step 1: Install via Composer
   • Step 2: Publish Configuration and Migrations
3. Configuration
   • Basic Settings
   • Customizing the Complaint Model
4. Usage
   • Adding the Reportable Trait
   • Creating a Complaint
   • Retrieving Complaints
   • Deleting a Complaint
5. Automatic Deletion of Old Complaints
   • Scheduler Configuration
   • Manual Deletion
6. Use cases
7. Testing
8. Want to Contribute?
9. License

Installation

Requirements

• PHP ^8.0
• Laravel ^9.0, ^10.0, ^11.0

Step 1: Install via Composer

composer require alyakin/reporting

Step 2: Publish Configuration and Migrations

php artisan vendor:publish --provider="Alyakin\Reporting\ReportingServiceProvider"
php artisan migrate

Ensure that your database settings are correct before running migrations.

Configuration

After installing the module, the configuration file is available at config/reporting.php. If the file is missing, run the following command:

php artisan vendor:publish --provider="Alyakin\Reporting\ReportingServiceProvider" --tag=config

Basic Settings

Example configuration file content:

return [
    'report_model' => \Alyakin\Reporting\Models\Report::class,
    'soft_delete_days' => 30,
];

Customizing the Complaint Model

If you need to extend the default model, update the report_model parameter in the configuration:

'report_model' => \App\Models\CustomReport::class,

The model must extend Alyakin\Reporting\Models\Report:

namespace App\Models;

use Alyakin\Reporting\Models\Report;

class CustomReport extends Report
{
    // Your additional methods or fields
}

Usage

Adding the Reportable Trait

Add the Reportable trait to any model that should support complaints:

use Alyakin\Reporting\Traits\Reportable;

class Post extends Model
{
    use Reportable;
}

Creating a Complaint

Use the reports() relationship to create a complaint:

$post = Post::find(1);
$user = $request->user();

$report = $post->addReport([
    'reason' => 'Спам',
    'meta' => ['severity' => 'низкий'],
], $user->id);

Retrieving Complaints

Retrieve all complaints for a model:

$reports = $post->reports;

Retrieve the related model from a complaint:

$post = $report->reportable;

Deleting a Complaint

Delete a complaint using standard Eloquent methods:

$report->delete();

Automatic Deletion of Old Complaints

Old complaints are deleted based on the soft_delete_days parameter in the configuration (default is 30 days).

Scheduler Configuration

Add the following line to app/Console/Kernel.php:

$schedule->command('model:prune')->daily();

Manual Deletion

Run the cleanup process manually:

php artisan model:prune

Use Cases

Here are five different examples of how this package can be applied across various domains:

1. Social Networks: Users can report posts or comments that violate guidelines...
2. E-commerce Platforms: Customers can flag products or sellers...
3. Content Management Systems (CMS): Readers can report offensive or incorrect content...
4. Customer Support Systems: Users can submit complaints linked to their accounts or tickets...
5. Educational Platforms: Students can report problems with course materials or instructors...

Testing

This package includes a test suite to ensure functionality works as expected. To run the tests:

composer test

PHPUnit

The package uses PHPUnit for feature and unit tests. You can run PHPUnit tests specifically with:

./vendor/bin/phpunit

Static Analysis

We use Larastan (PHPStan for Laravel) for static code analysis (with level 9):

./vendor/bin/phpstan analyse

Code Style

Laravel Pint is used for code style enforcement:

./vendor/bin/pint

Want to Contribute?

This package is open for community contributions!

You can:

• Explore the open issues to see what's planned
• Pick a task labeled good first issue or help wanted
• Suggest a new feature or improvement by opening an issue
• Fork the repository and submit a Pull Request

Contribution Requirements

When contributing to this package, please ensure:

1. Code Style: All code must follow our style guidelines. Run Laravel Pint before submitting:

   ./vendor/bin/pint

2. Static Analysis: Code must pass Larastan level 9 analysis:

   ./vendor/bin/phpstan analyse

3. Test Coverage: All new features or bug fixes must include tests.

4. Documentation: Update the README.md and other documentation to reflect any changes in functionality.

5. Feature Branches: Create a feature branch for your changes and submit a pull request against the main branch.

Current Roadmap Highlights

• Add support for Laravel-style events (e.g. ReportCreated, ReportDeleted)
• Artisan command to purge old reports (reporting:purge)

We welcome contributions, feedback, and ideas! 😊

License

This package is distributed under the MIT License.