Socials Laravel Package

Getting Started

This package is a Capell ecosystem social-links module: it stores and renders the social profiles attached to your app (or to Capell entities) as configurable links/icons. Treat it as a presentation + configuration package, not an OAuth/posting integration.

Minimal path:

1. composer require capell-app/socials — the release line is still 1.0.0-beta.*, so pin explicitly in composer.json (e.g. "capell-app/socials": "1.0.0-beta.51") rather than floating on ^1.0.
2. Publish config/assets: php artisan vendor:publish --tag=socials-config (and socials-assets / socials-views if those tags exist in vendor/capell-app/socials/src/SocialsServiceProvider.php). Read the service provider first — it is the fastest way to see registered tags, Blade namespace, and any singleton bindings.
3. Look first at config/socials.php and the package's resources/views directory. Those two files answer 90% of "how do I add a network / change markup" questions.
4. First use case: add a links (or profiles) array entry for a network and its URL, then drop the package's Blade component/partial into your footer layout to render the icon row.

If you are not already on Capell, verify the package's dependency constraints against your Laravel version before installing — Capell packages often track a narrow Laravel range, and a beta line can move it between releases.

Implementation Patterns

Config-driven profile list. Keep the network list in config (or a dedicated settings table if you need runtime editing), and let the view layer stay dumb. A typical shape is an associative array of network => ['url' => ..., 'label' => ..., 'icon' => ...]. Rendering then becomes a loop, and adding a network is a config change, not a template change.

Blade component wrapper. Rather than calling package partials directly in many layouts, wrap once: resources/views/components/social-links.blade.php that pulls config, filters empty URLs, and delegates to the package component. This gives you a single place to add rel="noopener noreferrer", target="_blank", aria-label, and sorting, and insulates you from beta-era view path changes.

Presenter / view-model for ordering and visibility. If different pages need different subsets (footer shows 4, contact page shows 7), add a small presenter or a Socials::only(['x','linkedin'])-style call in the wrapper instead of duplicating markup. Keep the filtering logic in PHP so it's unit-testable without rendering.

Settings/CMS integration. When used inside Capell, bind the profile list to whatever settings repository the CMS exposes, and cache the resolved array (Cache::remember('socials.links', ...)) with invalidation on save. This avoids a DB hit per render in a footer that appears on every page.

Testing pattern. Assert on rendered output rather than internals: $this->get('/')->assertSee('https://x.com/yourhandle') and assert the rel/target attributes. Because this is a beta, output-level tests survive internal refactors that unit tests on class names would not.

Asset handling. If the package ships icons as SVGs, prefer inlining via the published views (so they inherit currentColor) over <img> tags; it keeps hover states and dark mode working without extra CSS.

Gotchas and Tips

• Beta churn without readable notes. This release is beta.45 → beta.51 with only a compare link. Before bumping, run composer update capell-app/socials --dry-run and read the actual diff for config/, view paths, and any renamed config keys. In beta lines, config key renames are the most common silent breakage: your published config/socials.php will not be republished automatically, so new keys arrive as null/missing and sections render empty.
• Always diff published config against the vendor stub. diff config/socials.php vendor/capell-app/socials/config/socials.php after every bump. Merge new keys manually; never blindly overwrite if you have customised URLs.
• Empty-state rendering. Filter out entries with blank URLs before rendering or you get dead links and stray separators. Add an @if($links->isNotEmpty()) guard around the whole block.
• Security defaults. Any social URL comes from config or CMS input — treat it as user input if editors can change it. Enforce https://, add rel="noopener noreferrer" on target="_blank" links, and aria-label/visually-hidden text on icon-only anchors.
• View namespace caching. After publishing or editing package views, php artisan view:clear — stale compiled Blade for a namespaced component is a frequent "my change did nothing" false alarm.
• Debugging rendering issues. Use php artisan vendor:publish --tag=socials-views to copy views locally and add @dump($links) temporarily; publishing views is also the sanctioned escape hatch for markup changes you can't express via config.
• Extension points. The service provider is the place to look for Blade::componentNamespace, container bindings, and any Macroable registries — those are the stable-ish hooks. Prefer overriding via published views + a wrapper component over subclassing package classes, since beta internals can be renamed between releases.
• Version pinning in CI. With no readable release notes, pin the exact beta in composer.json and let Renovate/Dependabot open a PR you review against the changelog link, rather than allowing composer update to move the beta on its own.