Laravel Linkable Laravel Package

Product Decisions This Supports

• Unified Relationship Management:

  • Standardize how models establish and query relationships (e.g., posts linking to users, categories, or media) using a single trait, reducing inconsistency in relationship logic across the application.
  • Enable bidirectional linking (e.g., a "Post" linking to a "User" and vice versa) with minimal boilerplate, eliminating the need for custom pivot tables or middleware for each use case.

• Admin Panel Productivity:

  • Accelerate development of Laravel Nova or Filament admin panels by providing a pre-built Linkable field, reducing the time spent creating custom fields for managing relationships.
  • Support multi-lingual applications by integrating locale-aware relationship resolution and URL generation, ensuring a seamless experience for global teams.

• Content and Knowledge Management:

  • Build scalable features like "Related Content", "Hierarchical Structures", or "Tagging Systems" without reinventing the wheel for each relationship type.
  • Example: A CMS where articles can dynamically link to other articles, users, or categories, with searchable and filterable relationships.

• API and Frontend Consistency:

  • Ensure relationships and URLs generated for the API, admin panel, and frontend are consistent by centralizing logic in the Linkable trait.
  • Simplify API responses and frontend integrations by leveraging the package’s built-in methods (e.g., url(), previewUrl(), linkedTo()) to return standardized relationships and links.

• Roadmap for Scalability:

  • Phase 1: Implement basic linking for core models (e.g., posts, products, or support tickets).
  • Phase 2: Extend with validation rules (e.g., prevent circular links, enforce access control, or add relationship metadata like timestamps).
  • Phase 3: Integrate with search engines (e.g., Algolia) or analytics tools to track relationship performance and usage.

• Build vs. Buy Decision:

  • Buy: Avoid the overhead of building custom pivot tables, query logic, and Nova/Filament fields for relationships. The package provides a batteries-included solution with minimal setup.
  • Customize: If the package lacks specific features (e.g., relationship versioning, custom query scopes), assess whether extending it is more cost-effective than building from scratch. The trait and config system are designed for extensibility.

When to Consider This Package

• Adopt if:

  • Your application requires dynamic, queryable relationships between Eloquent models (e.g., finding all posts linked from a given article or user).
  • You’re using Laravel Nova or Filament and need a pre-built field for managing relationships in the admin panel.
  • Your team wants to reduce boilerplate for relationships (e.g., no need to manually create pivot tables or write custom query logic for each use case).
  • You prioritize developer velocity over fine-grained control (e.g., no need for highly customized relationship validation or UI).
  • Your application uses Laravel 10+ and PHP 8.2+, and the AGPL-3.0 license aligns with your project’s licensing (or you’re open to forking/relicensing).

• Look elsewhere if:

  • You need graph database features (e.g., complex traversal algorithms, pathfinding) → Consider Laravel + Neo4j or GraphQL Federation.
  • Your relationships require rich metadata (e.g., timestamps, user-specific permissions, or custom attributes) → Build a custom pivot table with additional fields or use a package like Laravel Many-to-Many.
  • You’re not using Laravel Nova or Filament and don’t need the admin panel integration.
  • The AGPL-3.0 license conflicts with your project’s licensing (e.g., proprietary software).
  • You require real-time relationship updates (e.g., WebSockets) → Consider Laravel Echo + Pusher for live synchronization or a dedicated real-time database.
  • You need advanced caching or CDN integration for relationships/URLs, as the package focuses on model-level relationships rather than infrastructure.

How to Pitch It (Stakeholders)

For Executives:

*"This package lets us build and manage relationships between content (e.g., articles, products, or support tickets) with minimal code, saving our team weeks of development time. Here’s how it helps our business:

• Faster Feature Delivery: Add ‘Related Content,’ ‘Hierarchical Structures,’ or ‘Tagging Systems’ in days, not weeks. For example:

  • Blog Platform: Automatically suggest related articles based on tags or categories.
  • E-commerce: Show ‘Frequently Bought Together’ or ‘Customers Also Viewed’ without manual database work.
  • Support System: Let agents flag ‘Related Tickets’ with a few clicks, improving response times.

• Consistent and Scalable Relationships: Ensure relationships work seamlessly across the admin panel, API, and frontend—no more broken links or inconsistencies. The package handles edge cases like duplicate relationships or circular references out of the box.

• Admin Efficiency: Give content managers a visual way to manage relationships in Nova or Filament, reducing training time and errors. For example, a content editor can drag-and-drop links between articles without touching code.

• Future-Proofing: Start with basic relationships and later add features like access control, analytics, or search integration as needed. The package is designed to grow with your product.

Risk Mitigation:

• The package is lightweight and actively maintained by Novius, with clear documentation and a clean codebase.
• While it uses AGPL-3.0, we can fork and relicense it if needed—this is a low-risk decision given its simplicity and focus on core functionality.
• It integrates smoothly with our existing Laravel stack, so adoption is low-effort and high-reward.

Ask: Let’s pilot this for one feature (e.g., ‘Related Articles’) and measure the time saved before scaling. The ROI is clear: less development time, more features, and happier users."*

For Engineering:

*"Problem: Managing relationships between models (e.g., ‘Post → Post,’ ‘User → Product’) typically requires:

1. A pivot table (e.g., post_relationships).
2. Eloquent relationships (belongsToMany, hasManyThrough, or custom queries).
3. Nova/Filament fields for the admin UI.
4. Query logic to traverse relationships (e.g., ‘find all posts linked from X’).
5. URL generation for linked resources.

Solution: novius/laravel-linkable gives us:

• Trait-Based Relationships: Add use Linkable to any model to enable dynamic relationships (e.g., Post::linkable()->attach(User::find(123))). No need for manual pivot tables or complex query logic.
• Nova/Filament Integration: Pre-built UI for selecting/deselecting relationships, with support for multi-lingual applications and locale-aware resolution.
• URL and Query Methods: Centralized logic for generating URLs (e.g., /posts/{slug}) and traversing relationships (e.g., linkedTo(), linkedFrom()), with support for query params, locales, and preview tokens.
• Extensibility: Override the trait or publish configs for customization (e.g., adding validation rules, custom query scopes, or relationship metadata).

Why Not Build?

• Saves 2–4 dev days per relationship feature.
• Handles edge cases (e.g., duplicate relationships, circular references, access control) out of the box.
• Reduces technical debt by standardizing relationship logic across the codebase.
• The package is modular: We can start with core features and extend as needed.

Tradeoffs:

• No GraphQL Support: We’d need to add that ourselves, but the underlying data structure is simple to expose via GraphQL.
• Limited Metadata: If we need to store additional data (e.g., ‘link strength,’ ‘created_by’), we’d need to extend the pivot table or use a custom solution.
• AGPL License: If this is a concern, we can fork the package and relicense it under MIT or another permissive license.

Proposal: Let’s use this package for our next relationship-heavy feature (e.g., ‘Related Content’ or ‘Product Bundles’) and evaluate its performance and maintainability. If it meets our needs, we can scale it across the application. If not, we can fork and extend it as needed.

Next Steps:

1. Review the documentation and usage examples.
2. Set up a proof-of-concept for one model (e.g., Post).
3. Test integration with Nova/Filament and the frontend.
4. Assess extensibility for our specific needs (e.g., validation, metadata)."*