#Walkthrough: moving a 1.x integration to 2.0

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// app/Providers/SignatureServiceProvider.php
class SignatureServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Signatories are Personnel; signatures belong to their login.
        $this->app->bind(SignatoryUserMapper::class, fn () => RelationUserMapper::using('user'));
    }

    public function boot(): void
    {
        // Vendor model, so Laravel's policy discovery never finds it.
        Gate::policy(Signature::class, DigitalSignaturePolicy::class);
    }
}

1
2
3

// bootstrap/providers.php
App\Providers\AppServiceProvider::class,
App\Providers\SignatureServiceProvider::class,

1
2
3

'documents' => [
    'accomplishment-report' => \App\Signatures\AccomplishmentReportDocument::class,
],

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

class AccomplishmentReport extends Model implements Signable
{
    use HasPdfTemplate, HasSignatories, SnapshotsSignatories, Tenantable;

    // Map each role to the column prefix you already have. No migration needed.
    public function signatoryRoles(): array
    {
        return [
            'attested' => 'attested_personnel',
            'noted'    => 'noted_personnel',
            'accepted' => 'accepted_personnel',
        ];
    }

    public function signatoryModel(): string
    {
        return Personnel::class;
    }

    public function attestedPersonnel(): BelongsTo
    {
        return $this->signatoryRelation('attested');
    }
    // notedPersonnel(), acceptedPersonnel(): same shape

    public function renderData(): array
    {
        return AccomplishmentReportService::viewData(
            AccomplishmentReportService::completedTasks($this->personnel, $this->dateRange()),
            $this->personnel,
            $this->dateRange(),
            $this->signatoryViewData('N/A'),   // attested_name, attested_position, …
        );
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

public function scopeForPeriod(Builder $query, Personnel $personnel, array $dateRange): void
{
    // whereDate, not equality: a `date` cast can store a time part on SQLite.
    $query->where('personnel_id', $personnel->id)
        ->whereDate('start_date', Carbon::parse($dateRange['start_date'])->toDateString())
        ->whereDate('end_date', Carbon::parse($dateRange['end_date'])->toDateString());
}

public static function newForPeriod(Personnel $personnel, array $dateRange): self
{
    return new static([
        'personnel_id' => $personnel->id,
        'start_date'   => Carbon::parse($dateRange['start_date'])->toDateString(),
        'end_date'     => Carbon::parse($dateRange['end_date'])->toDateString(),
    ]);
}

1
2
3
4
5
6
7
8

// before
$bind = fn (string $rel) => fn (AccomplishmentReport $r) => $r->{$rel}?->user;
new SlotDefinition(key: 'attested_by', /* … */ signatory: $bind('attestedPersonnel'));
renderer: new AccomplishmentReportRenderer,

// after
new SlotDefinition(key: 'attested_by', /* … */ signatory: 'attestedPersonnel');
renderer: new DomPdfRenderer(paper: 'a4'),

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

// app/Signatures/AccomplishmentReportDocument.php
class AccomplishmentReportDocument extends AbstractSignableDocument
{
    public function __construct(private PersonnelSignatoryDefaults $defaults) {}

    public function template(): string
    {
        return AccomplishmentReportTemplate::KEY;
    }

    public function preflight(): array
    {
        return [HasCompletedTasks::class];
    }

    public function locate(mixed $personnel, array $context = []): ?Model
    {
        return AccomplishmentReport::forPeriod($personnel, $context)->first();
    }

    public function open(mixed $personnel, array $context = []): Model
    {
        $report = $this->locate($personnel, $context)
            ?? AccomplishmentReport::newForPeriod($personnel, $context);

        if (! $report->hasBeenRoutedForSignatures()) {
            $report->issuance_date = $context['issuance_date'] ?? today()->toDateString();
            $report->snapshotSignatories($this->defaults);
        }

        $report->save();

        return $report;
    }

    // Keep your 1.x wording so users don't notice the move.
    public function messages(): array
    {
        return [
            'nothing_to_report'   => ['title' => 'Nothing to report', 'body' => 'There are no completed tasks in this period…'],
            'missing_signatories' => ['title' => 'No signatories set', 'body' => 'Set :roles under "Update Signatures" before routing this report.'],
            'routed'              => ['body' => 'Sent to :names. They\'ll sign in that order from the signature launcher.'],
            'already_routed'      => ['body' => 'This report is already with its signatories.'],
        ];
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

// app/Signatures/PersonnelSignatoryDefaults.php: who fills each role
class PersonnelSignatoryDefaults implements SignatoryDefaults
{
    public function for(Model $record, string $role): ?SignatoryAssignment
    {
        $settings = $record->personnel?->signature;   // the app's "Update Signatures" row
        $id = $settings?->{"{$role}_personnel_id"};

        return $id === null ? null : new SignatoryAssignment($id, $settings->{"{$role}_position"});
    }
}

// app/Signatures/Guards/HasCompletedTasks.php: refuse before anything is written
final class HasCompletedTasks implements PreflightGuard
{
    public function check(mixed $personnel, array $context): ?RoutingResult
    {
        return AccomplishmentReportService::completedTaskCount($personnel, $context) === 0
            ? RoutingResult::refused('nothing_to_report')
            : null;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12

trait HasAccomplishmentReportActions
{
    use RoutesDocumentsForSignatures;

    protected function routeAccomplishmentReportForSignatures(): void
    {
        // notifies, and on a refusal throws Halt so the modal stays open
        $this->routeDocument('accomplishment-report', $this->currentPersonnel(), $this->dateRange);

        $this->showingARPreview = false;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

protected function resolveAccomplishmentReport(Personnel $personnel): ResolvedDocument
{
    return app(DocumentOfRecordResolver::class)->resolve(
        'accomplishment-report',
        $personnel,
        $this->dateRange,
        live: fn (): string => AccomplishmentReportService::pdfFor($personnel, $this->dateRange),
    );
}

// Download
return $this->resolveAccomplishmentReport($personnel)
    ->download(AccomplishmentReportService::downloadFilename($personnel, $this->dateRange));

// Preview (an iframe of the bytes, under the "2 of 4 signed" banner)
$document = $this->resolveAccomplishmentReport($personnel);

return AccomplishmentReportService::previewHtml($document->contents(), $document->banner());

1
2
3

public static function pdfFor(Personnel $p, array $range): string              // draft bytes
public static function downloadFilename(Personnel $p, array $range): string    // "JDC-AR-Sep 01.pdf"
public static function previewHtml(string $pdf, ?HtmlString $banner = null): HtmlString

1
2
3
4
5
6
7
8
9

protected function getAccomplishmentReportHistoryAction(): Action
{
    return ViewDocumentHistoryAction::make('accomplishmentReportHistory')
        ->document('accomplishment-report')
        ->subject(fn (): ?Personnel => $this->currentPersonnel())
        ->context(fn (): array => $this->dateRange)
        ->label('AR signing history')
        ->outlined();
}

1
2
3
4
5
6

// before
$this->assertSame('Not ready for signatures', $result['title']);

// after
$result = app(DocumentRouter::class)->route('accomplishment-report', $this->preparer, self::PERIOD);
$this->assertSame(RoutingResult::NOT_READY, $result->reason());

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

class AccomplishmentReportDocumentContractTest extends TestCase
{
    use BuildsAccomplishmentReportScenario, RefreshDatabase, SignableDocumentContract;

    protected function setUp(): void
    {
        parent::setUp();
        $this->buildAccomplishmentReportScenario();
        $this->registerEveryone();
    }

    protected function documentKey(): string { return 'accomplishment-report'; }

    protected function routableSubject(): array { return [$this->preparer, self::PERIOD]; }

    protected function unroutableSubject(): ?array
    {
        $this->preparer->signature->update(['noted_personnel_id' => null]);

        return [$this->preparer->fresh(), self::PERIOD];
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13

public function test_a_routed_period_downloads_its_stored_document(): void
{
    app(DocumentRouter::class)->route('accomplishment-report', $this->preparer, self::PERIOD);

    // a task completed after routing must not show up
    Task::factory()->create([/* … same personnel, completed inside the period … */]);

    $stored = DocumentOfRecord::for(AccomplishmentReport::sole())->contents();
    $name   = AccomplishmentReportService::downloadFilename($this->preparer, self::PERIOD);

    $this->downloadFromTheBoard()
        ->assertFileDownloaded(str_replace('.pdf', '-in-progress.pdf', $name), $stored);
}