Fancybox Bundle Laravel Package

Getting Started

First, the honest framing: this is a Symfony2 bundle, not a Laravel package. It will not be auto-discovered by Composer, has no service provider, no facade, and no config/fancybox.php. If you composer require uran1980/fancybox-bundle in a Laravel app you will get the source on disk and nothing else — no routes, no views wired up, no assets published. That's fine, because the bundle is thin: it is essentially a wrapper around the jQuery FancyBox JS/CSS assets plus a small Twig/DI integration for Symfony.

So the minimal path for a Laravel developer is:

1. Look at Resources/public/ first. That's the actual payload — the FancyBox jquery.fancybox.js, CSS, and the sprite/loading images. Everything else in the bundle is Symfony plumbing you don't need.
2. Check composer.json to confirm which FancyBox major version is vendored (FancyBox 1.x and 2.x have completely different APIs and data-* attributes; 3.x is a rewrite with no jQuery dependency). This determines every markup example you write afterwards.
3. Copy or symlink the assets into public/vendor/fancybox/ (or better, install the upstream FancyBox release via npm/CDN and treat the bundle as reference only).
4. Load them in your layout after jQuery, since FancyBox 1/2 require window.jQuery to exist at init time.
5. Wire up your first use case: an image gallery lightbox. In Blade:

<a href="{{ asset('img/full/1.jpg') }}" data-fancybox="gallery">
    <img src="{{ asset('img/thumb/1.jpg') }}" alt="">
</a>

with a small init script:

$(function () {
    $('[data-fancybox]').fancybox({ loop: true });
});

If you genuinely are maintaining a legacy Symfony2 app rather than a Laravel one, the steps differ: register the bundle in AppKernel.php, then follow the bundle's Resources/config service definitions and publish assets with php app/console assets:install --symlink.

Implementation Patterns

Because the bundle contributes no application logic, the patterns below are about how you use FancyBox inside a Laravel codebase once you've lifted the assets across. Treat this as the day-to-day integration layer.

CDN/npm over the bundle. The lowest-friction pattern is to skip the bundle entirely for runtime and npm install @fancyapps/fancybox (v3+) or pin the 2.x build, then bundle it through Vite. You keep one dependency graph, get version pinning, and avoid a stale copy in public/vendor. Use the repo only as a reference for the asset list and legacy markup compatibility.

Gallery grouping via data-fancybox. Every anchor sharing a data-fancybox value becomes one gallery. In a Blade partial this is clean:

@foreach ($photos as $photo)
    <a href="{{ $photo->url }}" data-fancybox="post-{{ $post->id }}"
       data-caption="{{ $photo->caption }}">
        <img src="{{ $photo->thumb_url }}" alt="{{ $photo->caption }}">
    </a>
@endforeach

The post-{{ $id }} scoping is the important habit — it prevents lightboxes from distinct listings bleeding into one another when you render several galleries on one page.

Inline and AJAX modals. FancyBox 2 supports href="#some-hidden-div" for inline content and type: 'ajax' for remote fragments. The integration pattern in Laravel is to render the hidden div as a Blade component and let FancyBox clone it into the overlay:

$('#login-modal-link').fancybox({
    href: '#login-modal',
    type: 'inline',
    afterShow: function () { /* bind form handlers here, not on page load */ }
});

Rebinding inside afterShow matters because the overlay content is cloned, not moved — event listeners attached to the original node don't follow it.

Iframe for third-party pages. type: 'iframe' with explicit width/height and autoSize: false is the reliable combination for OAuth popups or embedded docs. Set data-fancybox-type="iframe" in markup for declarative use.

Wiring into a Blade layout cleanly. Keep a single resources/js/fancybox.js that imports the library and does the global data-fancybox bind, then @vite('resources/js/fancybox.js') in the layout. Avoid per-page inline scripts; you'll lose track of duplicate initializers and end up with two overlays stacking.

Server-side rendering of URLs. Never hardcode asset paths into the href when your storage driver might change. Storage::url() or a route helper keeps the lightbox working when you move from local disk to S3.

Gotchas and Tips

This is Symfony2 — it is dead software. Symfony2 reached end of life years ago, the bundle scores zero on every signal, and there is no maintenance. Don't build on it expecting fixes. Vendor it as reference or, more sensibly, go straight to FancyBox upstream.

jQuery ordering is the number-one bug. FancyBox 1/2 throw $ is not defined or silently no-op if the plugin script loads before jQuery. With Vite, import order in your entry file controls this; with plain <script> tags, order in the layout does. If lightboxes "just don't open," check the network tab and load order before anything else.

Version drift between the bundle and your markup. If the bundle vendors FancyBox 1.x, data-fancybox-group is the grouping attribute; in 2.x it's data-fancybox with a shared group value; in 3.x it's data-fancybox plus data-src. Copying examples from the docs of a different major version produces a lightbox that opens the wrong image or opens nothing. Confirm the vendored version first.

Asset publishing in Symfony vs. nothing in Laravel. In Symfony you need assets:install (and --symlink in dev) or the CSS/images 404 while the JS loads — a confusing half-broken state. In Laravel there is no publish step at all, which is why copying into public/ and committing is often more predictable than trying to make the bundle behave.

Overlay content and form submissions. Inline modals clone DOM. Forms inside them submit against whatever action is on the original node; if you generated <input type="hidden" name="_token"> once at page render, CSRF is fine, but any dynamically set hidden fields (e.g. an ID) will be stale. Set them in beforeLoad/afterShow instead.

Mobile and autoSize. FancyBox 2's autoSize misbehaves on mobile Safari with iframes; set fixed width/height and autoSize: false. Also test touch config if the vendored version predates touch support.

License hygiene. FancyBox 1.x was MIT/CC-BY; FancyBox 2.x and 3.x have commercial licensing terms for some uses. If you're shipping a product, check the upstream license for the version you're actually bundling — the repo's composer.json won't tell you clearly.

Extension point that actually matters. Since the bundle offers nothing to extend in Laravel, put your customization in one place: a Fancybox JS module exporting init() and options, called from your layout. That single seam is what you'll edit when you upgrade majors, swap CDNs, or replace the library with GLightbox/PhotoSwipe later.

Debugging checklist when nothing renders: (1) jQuery loaded? (2) plugin script 200 OK? (3) CSS loaded — no overlay styling means the JS ran but the stylesheet 404'd? (4) correct data-* attribute for the vendored major version? (5) any JS error earlier in the bundle aborting your init. Work down that list before touching config; there is no bundle config to touch anyway.