Laravel Linkable Laravel Package

Product Decisions This Supports

• Unified Linking Infrastructure:

  • Standardize how models generate URLs and establish relationships across the app (e.g., posts linking to users, categories, or media). Reduces inconsistency in URL generation (e.g., hardcoded routes vs. dynamic slugs).
  • Enables consistent link resolution for APIs, emails, and admin panels (e.g., /posts/{slug} vs. /posts/123).

• Admin Panel Efficiency:

  • Nova/Filament Integration: Replace manual belongsToMany fields for linking with a pre-built, searchable dropdown, cutting UI dev time by 40%.
  • Use Case: Content editors can link posts to related articles, products, or authors without writing SQL or querying pivot tables.

• API and Frontend Consistency:

  • GraphQL/REST Endpoints: Serialize linked relationships (e.g., post { links { title, url } }) without custom resolvers.
  • Frontend: Pass link data to Vue/React for dynamic UI (e.g., "You might also like:" cards).

• Roadmap for Scalability:

  • Phase 1: Replace ad-hoc linking logic (e.g., post->related_posts via raw queries).
  • Phase 2: Add validation (e.g., "prevent circular links") or analytics (e.g., track link clicks).
  • Phase 3: Extend to external links (e.g., track outbound clicks) or access control (e.g., "only admins can link to premium content").

• Build vs. Buy:

  • Buy: Avoid reinventing pivot tables + query logic for linking (e.g., post_linkables with source_id, target_id).
  • Customize: If the package lacks features (e.g., link expiration), assess whether forking or extending is cheaper than building from scratch (e.g., 1–2 dev weeks vs. 1 month).

• Use Cases:

  • Content Platforms: Blogs, wikis, or documentation where entities reference each other (e.g., "See also," "Prerequisites").
  • E-commerce: "Frequently bought together" or "Customers also viewed" without manual relationship setup.
  • Internal Tools: Linking support tickets, Jira issues, or Confluence pages in a custom portal.

When to Consider This Package

• Adopt if:

  • Your app needs dynamic, queryable links between Eloquent models (e.g., "find all posts linked from this article").
  • You’re using Laravel Nova/Filament and want a pre-built field for managing links in the admin panel.
  • Your team lacks bandwidth to build pivot tables + query logic for linking (e.g., post_linkables table with source_id, target_id).
  • You prioritize developer velocity over fine-grained control (e.g., no need for custom link validation or UI).
  • Your URLs are route-based (e.g., /posts/{post}) or slug-based (e.g., /posts/my-awesome-post), not hardcoded.

• Look elsewhere if:

  • You need graph database features (e.g., traversal algorithms, pathfinding) → Use Laravel + Neo4j or GraphQL Federation.
  • Your links require complex metadata (e.g., timestamps, user-specific permissions) → Build a custom pivot table with extra columns.
  • You’re not using Laravel 10+ or PHP 8.2+ (compatibility blocker).
  • The AGPL-3.0 license conflicts with your project’s licensing (e.g., proprietary software).
  • You need real-time link updates (e.g., WebSockets) → Combine this with Laravel Echo for live sync.
  • Links are static (e.g., hardcoded URLs) → Use Laravel’s built-in url() helper or a simple links table.

How to Pitch It (Stakeholders)

For Executives:

*"This package lets us add ‘linking’ between content (e.g., articles, products) with 3 lines of code, cutting dev time by 50% and reducing technical debt. Here’s why it’s a no-brainer:

Key Benefits:

1. Faster Feature Delivery:

   • Example: Adding ‘Related Posts’ to our blog takes hours (not days) because the package handles:
     • The database schema (no manual pivot tables).
     • The admin UI (Nova field for selecting links).
     • The frontend/API (URL generation and relationship queries).
   • Compare this to our current process: 2–3 dev days per linking feature.

2. Scalable for Growth:

   • If we launch a ‘Customers also viewed’ feature for e-commerce, this package lets us reuse the same linking logic across products, categories, and reviews.
   • No more siloed implementations (e.g., one team builds a post_linkables table, another builds a separate product_linkables table).

3. Admin Efficiency:

   • Content editors can drag-and-drop links in Nova without touching code. For example:
     • A marketer can link a blog post to a webinar registration page or a product page.
     • A support agent can flag related tickets without SQL knowledge.

4. Low Risk:

   • The package is lightweight (no bloat), with active maintenance (recent releases, CI checks).
   • If the AGPL license is a concern, we can fork and relicense it (though given its simplicity, this is unlikely to be needed).

ROI:

• Time Saved: 10–15 dev hours/month on linking features.
• Consistency: All links follow the same pattern (e.g., /posts/{slug}), improving SEO and UX.
• Future-Proof: Easy to extend for features like link analytics or access control.

Ask: Let’s pilot this for one feature (e.g., ‘Related Posts’) and measure the impact. If it saves even half the time we currently spend, it pays for itself in weeks."*

For Engineering:

*"Problem: Currently, linking models (e.g., Post → Post, Product → Category) requires:

1. A pivot table (post_linkables with source_id, target_id).
2. Eloquent relationships (hasManyThrough or custom queries).
3. Nova fields for the admin UI.
4. Query logic to traverse links (e.g., ‘find all posts linked from X’).
5. URL generation (e.g., /posts/{slug} vs. /posts/123).

This leads to:

• Inconsistent implementations (e.g., Team A uses slugs, Team B uses IDs).
• Boilerplate code (e.g., repeating attach()/detach() logic).
• Admin friction (e.g., no easy way to search/select linked models in Nova).

Solution: novius/laravel-linkable gives us:

Why Not Build?

• Time: Building this from scratch would take 1–2 dev weeks (pivot table, trait, Nova field, queries).
• Maintenance: We’d need to update it for every Laravel minor version.
• Edge Cases: The package already handles:
  • Duplicate links (prevents source_id → target_id duplicates).
  • Circular references (optional validation).
  • Localization (e.g., /fr/posts/{slug}).

Tradeoffs:

• No GraphQL Support: We’d need to add that ourselves (but the underlying data is already structured).
• AGPL License: If we fork, we’ll need to maintain it long-term. For now, the risk is low given its simplicity.
• Limited Customization: If we need link expiration or versioning, we’d need to extend the trait.

Proposal:

1. Pilot: Use it for one feature (e.g., ‘Related Posts’ in the blog).
   • Add use Linkable to the Post model.
   • Configure linkableConfig() with routeName, optionLabel, etc.
   • Test the Nova field for linking.
2. Measure:
   • Compare dev time vs. a custom implementation.
   • Verify URL generation works for slugs/IDs.
3. Scale:
   • Roll out to other link-heavy areas (e.g., support tickets, products).
   • Extend for analytics (e.g., track link clicks)