Pumukit Timed Pub Decisions Bundle Laravel Package

Getting Started

This is a small, single-maintainer Pumukit add-on (1 star, no dependents), so treat it as an internal Teltek bundle you are vendoring rather than a stable public dependency. It layers "publication decisions with a timestamp" on top of Pumukit's existing MultimediaObject publication status model — i.e. it lets you say "publish this video at 09:00 on Monday" or "unpublish it after the event" instead of flipping status by hand.

1. Install from VCS, not Packagist. There is almost certainly no stable release, so pin a commit:

{
  "repositories": [
    { "type": "vcs", "url": "https://github.com/teltek/PumukitTimedPubDecisionsBundle" }
  ],
  "require": {
    "teltek/pumukit-timed-pub-decisions-bundle": "dev-master"
  }
}

Commit the resulting composer.lock — with a 1-star repo, dev-master is a moving target and a force-push will break your build.

2. Register the bundle after the Pumukit core bundles so its Doctrine ODM mappings and compiler passes see PumukitSchemaBundle first:

// Symfony 3.x: app/AppKernel.php
new Pumukit\TimedPubDecisionsBundle\PumukitTimedPubDecisionsBundle(),

// Symfony 4/5: config/bundles.php
Pumukit\TimedPubDecisionsBundle\PumukitTimedPubDecisionsBundle::class => ['all' => true],

3. Read these four places first — in this order — because the README will be thin:

• composer.json — confirms which Pumukit/Symfony major it targets. This bundle is version-sensitive; a Symfony 3 bundle will not boot on a Symfony 5 Pumukit.
• Document/ — the ODM document mapping the decision (timestamp + target MultimediaObject + desired status). This is your data model; everything else is glue.
• Command/ — the console command that sweeps due decisions. This is the actual engine.
• Resources/config/services.xml (or config/services.yaml) — shows what is public, what is decorated, and which repository/service you can inject.

4. First use case. After installing and running bin/console doctrine:mongodb:schema:update (Pumukit is MongoDB/ODM), run:

bin/console list pumukit

and look for the timed-publication command. Run it with -vvv on a dev instance with one multimedia object scheduled a minute in the future. If the object's status flips, you understand the bundle; if not, the command name, the cron, or the timezone is wrong — that is the whole debugging surface.

Implementation Patterns

Create decisions programmatically rather than by hand. Whatever the admin UI exposes, the reliable integration is to build the bundle's document in your own service and persist it with the ODM document manager:

$decision = new TimedPubDecision();          // check Document/ for the real FQCN
$decision->setMultimediaObject($mm);
$decision->setStatus(MultimediaObject::STATUS_PUBLISHED);
$decision->setTime(new \DateTime('2024-06-01 09:00:00'));

$dm->persist($decision);
$dm->flush();

Use this inside your own importers, editorial workflows, or a custom admin action — it keeps you independent of the bundle's controller layer, which is the part most likely to change.

Drive it from cron, not from a web request. Pumukit deployments normally schedule maintenance through crontab entries under the web user. Add the sweep alongside the existing Pumukit jobs:

*/5 * * * * cd /var/www/pumukit && bin/console <bundle-command> --env=prod -q

Five minutes is a sensible granularity unless your editors schedule to the second.

Treat the decision object as a queue, and the MultimediaObject as the projection. Do not read pending decisions to render public pages — always read $mm->getStatus(). The decision table is write-mostly and grows; the object status is what your templates already understand. This split keeps the bundle from leaking into your view layer.

Reschedule by cancelling, not by mutating. When an editor moves a publication date, create a new decision and delete/mark the old one rather than editing the timestamp in place. Mutating a row the sweep command may be mid-read on is the classic race in this pattern, and a superseded-row approach gives you an audit trail for free.

Wrap the command if you need side effects. If publishing must also trigger a notification, an encoder job, or a cache purge, do not patch the bundle's command. Register your own command that invokes the bundle's service (or the command via Application::find()/run()) and then fires your own logic. Decoration via services.yaml is the cleaner variant if the sweep logic lives in a service rather than in execute().

Test with fixtures and a frozen clock. Because the only interesting behaviour is "is time in the past?", the test is: create objects with time in the past and future, run the command's execute() with an ArrayInput/NullOutput, assert statuses. Keep a small kernel test — you do not need a browser.

Gotchas and Tips

Timezone is the number-one failure. DateTime is stored as a BSON date (UTC), but editors think in local time and Pumukit's php.ini/default_timezone may differ between CLI and FPM. If decisions fire hours early or late, this is why. Always construct decision times with an explicit timezone and verify what the cron user's date.timezone is — CLI and web often read different php.ini files on the same box.

Cron environment ≠ web environment. The command needs the same APP_ENV, cache directory permissions, and MongoDB credentials as the site. A sweep that silently does nothing in prod while working in dev is nearly always cache or permissions (var/cache owned by root after a manual run).

Idempotency and overlap. If the sweep is not guarded, two overlapping cron runs can apply the same decision twice. Check whether the bundle deletes or flags processed rows; if it does neither, add a lock (a simple flock on a lockfile in the cron line is enough) and make your downstream listeners tolerant of repeat application.

Zero dependents means zero field-testing. Expect rough edges in the admin templates, missing translations, and hard-coded assumptions about which statuses are "publishable". Read Document/ and the command before trusting the UI. Pin the commit hash and be prepared to fork: with 1 star, an issue you file may never be answered, and a fork under your own org costs you nothing.

Do not rely on MultimediaObject events firing. Pumukit's own listeners (search indexing, sitemaps, broadcast pub channels) may or may not be triggered by a status change made from this bundle's command rather than from the admin controller. If newly published videos do not appear in search or on the portal after a scheduled publish, this is the cause — dispatch the equivalent Pumukit event yourself, or call the same service the admin controller calls.

Extension points, in order of safety: (1) your own command wrapping theirs, (2) service decoration in services.yaml, (3) template override via Resources/PumukitTimedPubDecisionsBundle/views/... in your app, (4) forking. Avoid (3) and (4) until you have a reason — the view layer here is the least stable part.

Schema updates are manual. New ODM documents mean doctrine:mongodb:schema:update (or index creation) on every environment. Add it to your deploy script; forgetting it produces an empty-but-not-erroring behaviour that is confusing to debug.