README

Construction work planning engine with critical-path scheduling, Gantt chart generation, and host-integratable HTTP controllers.

Features

• Schedule generation — template-driven activity durations, dependencies, and working-day calendars
• Critical Path Method (CPM) — early/late dates, slack, and critical path day counts
• Gantt engine — timeline columns, bar positioning, milestone support
• Template validation — duration percent totals, dependency integrity, work-type matching
• HTTP controllers — projects, templates, calendar, dashboard, reports, exports, settings, users (via host closures)
• UI kit — reusable PHP view components, CSS, and JavaScript (Gantt, calendar, dashboard)
• Publishable assets — config, migrations, seeds, views, menu, and permission manifests
• Framework adapters — contracts for request, response, session, authorization, CSRF, views, and database
• Laravel support — auto-discovery, config merge, and workplanner:publish Artisan command

Requirements

• PHP 8.3 or higher
• Composer 2.x

Optional (host integrations):

• dompdf/dompdf ^3.0 — PDF exports
• phpoffice/phpspreadsheet ^5.8 — Excel exports
• illuminate/support ^11|^12 — Laravel auto-discovery

Installation

Any PHP application

composer require workplanner/work-planner

Laravel

composer require workplanner/work-planner
php artisan vendor:publish --tag=workplanner-config
php artisan vendor:publish --tag=workplanner-migrations
php artisan workplanner:publish

Register host bridge adapters in your application bootstrap (see Host integration).

Configuration

Default configuration ships in config/workplanner.php:

return [
    'name' => 'Work Planner',
    'pagination' => ['per_page' => 10],
    'calendar' => ['default_duration_days' => 180],
    'theme' => ['default' => 'system'],
];

Access merged config in PHP:

use WorkPlanner\WorkPlannerServiceProvider;

$perPage = WorkPlannerServiceProvider::config('pagination')['per_page'] ?? 10;

Laravel reads the same values from config('workplanner') after publishing.

Publishing assets

Publish tags:

Standalone PHP host:

php vendor/bin/workplanner-install          # list tags and publish all
php vendor/bin/workplanner-install --tag=workplanner-config

Or programmatically:

use WorkPlanner\PackageInstaller;
use WorkPlanner\WorkPlannerServiceProvider;

$installer = new PackageInstaller('/path/to/host');
$installer->publish(WorkPlannerServiceProvider::TAG_CONFIG);
$installer->publishAll();

Usage examples

Generate a schedule (core engine)

use WorkPlanner\Calendar\WorkingCalendar;
use WorkPlanner\DTO\ProjectInputDTO;
use WorkPlanner\Template\TemplateActivity;
use WorkPlanner\Template\TemplateCollection;
use WorkPlanner\Template\TemplateDependency;
use WorkPlanner\WorkPlanner;

$template = new TemplateCollection(workTypeId: 1, versionId: 1);
$template->addActivity(new TemplateActivity(1, 'Mobilization', 40.0, '#3498db', false, 5, 1));
$template->addActivity(new TemplateActivity(2, 'Handover', 60.0, '#9b59b6', true, 1, 2));
$template->addDependency(new TemplateDependency(1, 2));

$input = new ProjectInputDTO(
    workTypeId: 1,
    template: $template,
    startDate: new DateTimeImmutable('2026-07-01'),
    calendar: new WorkingCalendar([1, 2, 3, 4, 5]),
    durationDays: 30,
);

$result = (new WorkPlanner())->generate($input);

echo $result->criticalPathDays;
foreach ($result->activities as $activity) {
    echo $activity->name, ' ', $activity->startDate->format('Y-m-d'), PHP_EOL;
}

Host integration

Package controllers depend on host closures — thin wrappers in your application wire repositories and services:

use WorkPlanner\Http\Controllers\ProjectController;
use WorkPlanner\WorkPlannerServiceProvider;

WorkPlannerServiceProvider::registerHostBridge(static function ($registry): void {
    $registry->request($hostRequestAdapter);
    $registry->response($hostResponseAdapter);
    $registry->session($hostSessionAdapter);
    $registry->authorization($hostAuthorizationAdapter);
    $registry->views($hostViewFactory);
});

WorkPlannerServiceProvider::boot();

See the reference host wrappers in the Work Planner application repository under app/Controllers/.

Screenshots

Dashboard	Gantt chart

Project calendar	Template builder

Screenshot files are not bundled in the Composer package. Add your own captures under docs/screenshots/ in the application repository.

Troubleshooting

ProjectInputDTO deprecation warnings (PHP 8.3+)

Use named arguments and place calendar before optional endDate / durationDays. See UPGRADE.md.

Service not registered: WorkPlanner\Contracts\...

Call WorkPlannerServiceProvider::registerHostBridge() before boot() and register all required contract adapters.

Published assets missing

Ensure workplanner-assets tag was published and web server serves public/vendor/workplanner/.

Laravel provider not discovered

Confirm illuminate/support is installed and run php artisan package:discover.

Migrations fail on fresh install

Run migrations in order from database/migrations/vendor/workplanner (or published path). Seed permissions using published seeders before creating users.

Testing

composer test
# or
php tests/WorkPlannerGenerateTest.php

License

MIT — see LICENSE.

Changelog

See CHANGELOG.md.