README

Eloquent Relation Guard

Laravel package by MuhammadObadaa

Scan, inspect, and (optionally) force‐delete Eloquent models along with their HasOne/HasMany branches—without relying on database‐level cascade or restrict rules.

OnDelete, you can walk through a model’s HasOne/HasMany relations (to any depth), get a nested “tree” of related IDs, check whether a model is safe to delete, or forcibly delete the entire sub‐tree in one shot.

Installation

Require the package via Composer:

composer require mhdobd/eloquent-relation-guard

Configuration

Publish the configuration file:

php artisan vendor:publish --provider="EloquentRelation\Guard\EloquentRelationGuardServiceProvider" --tag="config"

This will copy config/eloquent-relation-guard.php into your application’s config/ directory.

Usage

1. Use the Trait in Your Model Add the HasRelationalDependencies trait to any Eloquent model you want to protect/scan.

   use Illuminate\Database\Eloquent\Model;
   use Illuminate\Database\Eloquent\Relations\HasMany;
   use EloquentRelation\Guard\Traits\HasRelationalDependencies;
   
   class Post extends Model
   {
       use HasRelationalDependencies;
   
       /**
        * By default, all HasOne/HasMany relations will be scanned.
        * If you want to limit or specify nested branches, define:
        */
       protected array $scanRelations = [
           'comments',             // only scan Post::comments()
           'comments.replies',     // also scan replies under each comment
           'tags',                 // scan Post::tags() (if tags is a HasMany relationship)
           '*'                     // or simply, add all first-level relations
       ];
   
       // Type hint (mention the return type of) each HasOne/HasMany relation method
       public function comments(): HasMany
       {
          return $this->hasMany(Comment::class);
       }
   }

2. Check if a Record Can Be Deleted

   $post = Post::find(42);
   
   if ($post->canBeSafelyDeleted()) {
       // no related HasOne/HasMany records exist
       $post->delete();
   } else {
       // there are related records—perhaps alert the user
       // so you can alert the user with detailed related relations using $post->relationStructure
   }

3. Get the Full Relation “Tree” (with IDs)

   $post = Post::find(42);
   
   // Pass a depth (integer) to limit how many levels deep to scan.
   // Use -1 for no depth limit, only memory and time one.
   $tree = $post->relationStructure(depth:2);
   // $tree will look like:
   // [
   //   'comments' => [
   //       'ids'   => [10, 11, 12],
   //       'model' => 'App\Models\Comment',
   //       'nested'=> [
   //           'replies' => [
   //               'ids'   => [101, 102],
   //               'model' => 'App\Models\CommentReply',
   //               'nested'=> [ /* … */ ],
   //           ],
   //       ],
   //   ],
   //   'tags' => [
   //       'ids'   => [5, 6],
   //       'model' => 'App\Models\Tag',
   //       'nested'=> [],
   //   ],
   // ]

4. Force‐Delete a Model and All Related Records

   $post = Post::find(42);
   $deletedCount = $post->forceCascadeDelete();
   // This will delete all HasOne/HasMany descendants (ignoring DB foreign‐key rules)
   // and then delete the Post itself. $deletedCount is the total number of records removed.

5. Console Command: record:tree You can visualize a model’s relation tree (with IDs) from the CLI:

   php artisan record:tree Post 42 2

   • Post : The model class name, it should be located in app/models/ directory
   • 42 : ID of the record to inspect
   • 2 : Depth (how many nested levels to scan; use -- -1 for unlimited)

   Example Output:

   Relation Tree for App\Models\Post (ID: 42) | Depth: 2
   ├── comments (App\Models\Comment): [10, 11, 12]
   │   └── replies (App\Models\CommentReply): [101, 102]
   └── tags (App\Models\Tag): [5, 6]
   

for more details check the Documentation

TODO

• Add support for soft deletes (detecting deleted_at and deciding whether to include or ignore soft‐deleted records).
• Support morph relations along with HasOne and HasMany relations.
• Allow configurable thresholds for maximum nodes/depth before aborting the scan.
• Add event hooks (e.g., beforeDeleteGuarded, afterDeleteGuarded) so users can tap into the delete process.
• Provide Laravel Nova/Filament integrations for visual “Are you sure?” modals.
• Mark visited classes when DFS over them so it can avoid cyclic database relations.
• Write feature tests and include sample migrations/seeders.
• Add Complexity Details in documentation file.
• Optimize Time, Memory, and DB Query complexity over core package logic implementation.

Contributing

If you discover bugs, have feature requests, or want to contribute code, please use the GitHub issue tracker:

Issues & Contributions: https://github.com/MuhammadObadaa/eloquent-relation-guard/issues

Feel free to fork the repository, open a PR, and follow these basic guidelines:

1. Fork the repo and create a new branch for your feature/fix.
2. Write at least one test (where applicable) demonstrating the expected behavior.
3. Update CHANGELOG.md and README.md if you add or change functionality.
4. Submit a pull request—describe what you changed and why.

License

Eloquent Relation Guard package is open source, licensed under MIT. Feel free to use, modify, and redistribute.