Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
57.89%
11 / 19
37.50%
3 / 8
 CRAP
0.00%
0 / 1
Action
57.89%
11 / 19
37.50%
3 / 8
 20.03
0.00%
0 / 1
 uri
100.00%
1 / 1
100.00%
1 / 1
 1
 goTo
0.00%
0 / 1
0.00%
0 / 1
 2
 goToRemote
0.00%
0 / 2
0.00%
0 / 1
 6
 javascript
100.00%
1 / 1
100.00%
1 / 1
 1
 launch
0.00%
0 / 3
0.00%
0 / 1
 2
 namedAction
100.00%
1 / 1
100.00%
1 / 1
 1
 resetForm
88.89%
8 / 9
0.00%
0 / 1
 3.01
 submitForm
0.00%
0 / 1
0.00%
0 / 1
 2
1<?php
2
3declare(strict_types=1);
4
5namespace Phpdftk\Pdf\Writer;
6
7use Phpdftk\Pdf\Core\Action\Action as CoreAction;
8use Phpdftk\Pdf\Core\Action\GoToAction;
9use Phpdftk\Pdf\Core\Action\GoToRAction;
10use Phpdftk\Pdf\Core\Action\JavaScriptAction;
11use Phpdftk\Pdf\Core\Action\LaunchAction;
12use Phpdftk\Pdf\Core\Action\NamedAction;
13use Phpdftk\Pdf\Core\Action\ResetFormAction;
14use Phpdftk\Pdf\Core\Action\SubmitFormAction;
15use Phpdftk\Pdf\Core\Action\URIAction;
16use Phpdftk\Pdf\Core\Document\Destination;
17use Phpdftk\Pdf\Core\FileSpec\FileSpec;
18use Phpdftk\Pdf\Core\PdfArray;
19use Phpdftk\Pdf\Core\PdfName;
20use Phpdftk\Pdf\Core\PdfReference;
21use Phpdftk\Pdf\Core\PdfString;
22
23/**
24 * Static factory for the most common PDF action types. Each method
25 * returns an `Action` subclass ready to be assigned to
26 * `Catalog::$openAction`, an annotation's `/A` entry, or a form
27 * field's `/AA` (additional actions) dict.
28 *
29 * For action types not covered here, construct the relevant
30 * `Phpdftk\Pdf\Core\Action\*` class directly.
31 */
32final class Action
33{
34    /** URI action — open a URL in the user's browser. */
35    public static function uri(string $url): URIAction
36    {
37        return new URIAction(new PdfString($url));
38    }
39
40    /** GoTo action — jump to an explicit destination within this document. */
41    public static function goTo(Destination|PdfReference $target): GoToAction
42    {
43        return new GoToAction($target);
44    }
45
46    /**
47     * GoToR (Go-to-remote) — jump to a destination in another PDF.
48     * `$dest` may be a destination array, a name string referring to a
49     * named destination, or a `Destination` value object.
50     */
51    public static function goToRemote(string $file, Destination|PdfReference|string $dest): GoToRAction
52    {
53        $destValue = is_string($dest) ? new PdfString($dest) : $dest;
54        return new GoToRAction(new PdfString($file), $destValue);
55    }
56
57    /** JavaScript action — execute the given source string when triggered. */
58    public static function javascript(string $code): JavaScriptAction
59    {
60        return new JavaScriptAction(new PdfString($code));
61    }
62
63    /**
64     * Launch action — run an application or open a file via the
65     * platform's default handler.
66     */
67    public static function launch(string $file): LaunchAction
68    {
69        $action = new LaunchAction();
70        $action->f = new FileSpec($file);
71        return $action;
72    }
73
74    /**
75     * Named action — one of the four predefined names (`NextPage`,
76     * `PrevPage`, `FirstPage`, `LastPage`) or a viewer-specific
77     * extension.
78     */
79    public static function namedAction(string $name): NamedAction
80    {
81        return new NamedAction(new PdfName($name));
82    }
83
84    /**
85     * Reset-form action — clear form field values to their defaults.
86     * `$fields` is an optional list of field names; `null` resets all.
87     * `$includeExclude` controls /Flags bit 1 (true = include, false = exclude).
88     *
89     * @param list<string>|null $fields
90     */
91    public static function resetForm(?array $fields = null, bool $includeExclude = false): ResetFormAction
92    {
93        $action = new ResetFormAction();
94        if ($fields !== null) {
95            $action->fields = new PdfArray(array_map(
96                static fn(string $f) => new PdfString($f),
97                $fields,
98            ));
99        }
100        if ($includeExclude) {
101            $action->flags = 1;
102        }
103        return $action;
104    }
105
106    /**
107     * Submit-form action — post form field values to an HTTP endpoint.
108     */
109    public static function submitForm(string $url): SubmitFormAction
110    {
111        return new SubmitFormAction(new FileSpec($url));
112    }
113}