Progress Widget Laravel Package

Getting Started

Read this first: it is not a Laravel package. friendsofvictoire/progress-widget is a Symfony bundle for Victoire DCMS, a widget/page-builder CMS built on Symfony 2/3. It ships a WidgetProgress entity, a Symfony Form type, a config.yml widget registration, and Twig templates. There is no service provider, no facade, no config publish, and it will not autoload in a Laravel app.

So "getting started" for a Laravel developer means evaluating it as reference material, not as a dependency:

1. Do not composer require it. The constraint set predates PHP 7.2 and will either fail resolution on PHP 8 or drag in Symfony 2.x components you don't want in a Laravel project.

2. Clone/zip the repo and read three things, in this order:

   • Resources/views/** — the Twig template(s) for the front-end render. This is the actual progress-bar markup (label, track, fill, percentage).
   • Form/WidgetProgressType.php — the field set the widget exposes to editors (label, value, max, colour/variant, etc.). This is your spec for the Blade/Livewire form.
   • Resources/config/config.yml — how Victoire registers a widget (slot, category, icon). Useful only if you're cloning the page-builder concept.

3. First use case: lift the markup into a Blade component so content editors get a progress bar without hand-writing HTML:

   <x-progress :value="72" label="Onboarding" variant="emerald" />
   

That is the real day-one win — about 30 lines of Blade plus the CSS in the template — not the bundle itself.

Implementation Patterns

Pattern A — Blade component port (the 90% case). Copy the Twig template's structure into resources/views/components/progress.blade.php, replace the inline percentage with a computed clamped value, and use your own utility classes rather than the Victoire theme classes:

@props(['value' => 0, 'max' => 100, 'label' => null, 'variant' => 'indigo'])

@php
    $max = $max > 0 ? $max : 100;
    $pct = max(0, min(100, round($value / $max * 100)));
@endphp

<div {{ $attributes->merge(['class' => 'w-full']) }}>
    @if ($label)
        <div class="flex justify-between text-sm mb-1">
            <span>{{ $label }}</span>
            <span>{{ $pct }}%</span>
        </div>
    @endif
    <div class="h-2 rounded bg-gray-200" role="progressbar"
         aria-valuenow="{{ $pct }}" aria-valuemin="0" aria-valuemax="100">
        <div class="h-2 rounded bg-{{ $variant }}-600" style="width: {{ $pct }}%"></div>
    </div>
</div>

Pattern B — mimic Victoire's widget registration in your own page builder. Victoire's value is that a widget is a described, reorderable block. If you're building a CMS-ish admin, copy that contract: a config/widgets.php map of key => [label, icon, form, view, defaults], resolved by a WidgetRenderer that @includes the matching Blade view and merges stored attributes. This gives you Victoire's editor UX without Symfony.

Pattern C — persistence. Victoire stores widget settings on a widget entity tied to a page. The Laravel equivalent is a JSON column plus a cast:

protected $casts = ['settings' => ProgressSettings::class];

Keep value, max, label, variant as the stable data contract — the same four fields the bundle's form type exposes — so the Blade component, the Livewire editor, and any API output stay in sync.

Pattern D — Livewire editor. Pair the Blade component with a Livewire\ProgressEditor that validates value: numeric|min:0, max: numeric|min:1, and renders a live preview. This is the closest thing to the Victoire editing experience and is where the "widget" idea actually pays off.

Integration tips:

• Prefer style="width: X%" over dynamic Tailwind classes (w-[72%]) unless your build scans the rendered output — safelisted variants, not computed widths.
• If your $value is currency or a count, accept value/max raw and compute the percentage in the component; don't ask editors for percentages.
• Translate the label server-side (__()), not in the template, so the component stays presentation-only.

Gotchas and Tips

• Abandoned since 2016-08-22, 0 stars, 0 dependents. No security patches, no PHP 8 compatibility, no Symfony 4+ support. Treat it as a code sample under whatever the repo's LICENSE says (verify before copying — if there's no license file, you technically have no grant to reuse it).
• Namespace/autoload mismatch is the first failure mode. FriendsOfVictoire\WidgetProgressBundle will never be discovered by Laravel's package discovery; if you somehow install it, you'll get "class not found" or a Symfony kernel-boot error, not a helpful message.
• It depends on Victoire core. The widget entity references a Victoire page/Widget base class and business entity. You cannot extract "just the progress bar" via composer — extract it from the templates by hand.
• Division by zero / out-of-range values. The original form type almost certainly does not clamp. Always guard max > 0 and clamp to 0..100; a negative or >100 width silently breaks layout.
• Accessibility is likely missing. Symfony 2-era widget templates rarely include role="progressbar" or aria-valuenow. Add them in your port — it's free and it's the main thing you'd otherwise inherit as a defect.
• CSS leakage. Victoire templates are written against a specific theme's classes. Copying them verbatim into Tailwind/Bootstrap gives you unstyled or half-styled output; rewrite class names rather than importing their stylesheet.
• Debugging approach: since you can't run it, read the Twig template as the source of truth, render it once in a throwaway Symfony/Victoire sandbox only if you must confirm the visual, and otherwise diff your Blade output against the template's HTML structure.
• Extension points you'd actually want (and don't exist here): indeterminate/animated state, segmented/multi-step progress, and a circular variant. The bundle is a flat bar only — budget for building these yourself rather than waiting on upstream.
• Recommendation: do not add this as a dependency. Spend the hour porting the markup, and if you need a maintained Laravel-side progress primitive, build the Blade component (Pattern A) or reach for a UI kit. Score 0.06 is accurate — this is archive reference, not a library.