{"id":18765319,"url":"https://github.com/setasign/setapdf-signer-addon-safe","last_synced_at":"2025-12-07T17:30:14.044Z","repository":{"id":63196209,"uuid":"564687758","full_name":"Setasign/SetaPDF-Signer-Addon-SAFE","owner":"Setasign","description":"A signature add-on for the SetaPDF-Signer component for the \"Serviço de Assinatura de Faturas Eletrónicas\" (SAFE) of the Portuguese State","archived":false,"fork":false,"pushed_at":"2022-12-01T08:56:24.000Z","size":2099,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-16T15:05:48.014Z","etag":null,"topics":["digital-signature","pades","pdf","php","safe","setapdf-signer","signature"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Setasign.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-11-11T09:05:38.000Z","updated_at":"2022-12-01T08:59:25.000Z","dependencies_parsed_at":"2023-01-23T12:01:20.608Z","dependency_job_id":null,"html_url":"https://github.com/Setasign/SetaPDF-Signer-Addon-SAFE","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Setasign%2FSetaPDF-Signer-Addon-SAFE","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Setasign%2FSetaPDF-Signer-Addon-SAFE/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Setasign%2FSetaPDF-Signer-Addon-SAFE/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Setasign%2FSetaPDF-Signer-Addon-SAFE/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Setasign","download_url":"https://codeload.github.com/Setasign/SetaPDF-Signer-Addon-SAFE/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239663498,"owners_count":19676591,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["digital-signature","pades","pdf","php","safe","setapdf-signer","signature"],"created_at":"2024-11-07T18:33:33.818Z","updated_at":"2025-12-07T17:30:13.675Z","avatar_url":"https://github.com/Setasign.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SetaPDF-Signer-Addon-SAFE\n\nThis package offers a module for the SetaPDF-Signer component that allows you\nto use the [\"Serviço de Assinatura de Faturas Eletrónicas\" (SAFE)](https://www.autenticacao.gov.pt/servi%C3%A7o-de-assinatura-de-faturas-eletr%C3%B3nicas-safe-)\nof the Portuguese State to digital sign PDFs in pure PHP.\n\n## Comments and notes on the implementation\n\n- While the documentation says that the API conforms to the CSC API we noted several\n  differences which makes it impossible to use our existing [CSC API module](https://github.com/Setasign/SetaPDF-Signer-Addon-CSC).\n- As we do not understand or speak Portuguese while the official documentation is only\n  available in Portuguese, we tried to implement the API based on an\n  [automated translation](/docs/AMA%20-%20SAFE%20Documento%20de%20integração-EN.pdf)\n  and the OpenAPI Specification definitions found on the projects official\n  [GitHub repository](https://github.com/amagovpt/doc-SAFE/tree/main/api).\n- We're also not able to authenticate as a Portuguese citizen and were dependent on\n  users to provide test credentials/tokens.\n- The hashing algorithm is fixated to SHA256 as per documentation and the information from the /credentials/info\n  endpoint are ignored.\n\n## Requirements\n\nYou need to have credentials and a valid access token to the SAFE API endpoints. \n\nThis package is developed and tested on PHP \u003e= 8.0. Requirements of the\n[SetaPDF-Signer](https://www.setasign.com/signer)\ncomponent can be found [here](https://manuals.setasign.com/setapdf-signer-manual/getting-started/#index-1).\n\nWe're using [PSR-17 (HTTP Factories)](https://www.php-fig.org/psr/psr-17/) and\n[PSR-18 (HTTP Client)](https://www.php-fig.org/psr/psr-18/) for the requests. So you'll need an implementation of\nthese. We recommend using Guzzle.\n\n```\n    \"require\" : {\n        \"guzzlehttp/guzzle\": \"^7.0\",\n        \"http-interop/http-factory-guzzle\": \"^1.0\"\n    }\n```\n\n## Installation\nAdd following to your composer.json:\n\n```json\n{\n    \"require\": {\n        \"setasign/setapdf-signer-addon-safe\": \"^1.0\"\n    },\n    \"repositories\": [\n        {\n            \"type\": \"composer\",\n            \"url\": \"https://www.setasign.com/downloads/\"\n        }\n    ]\n}\n```\n\nand execute `composer update`. You need to define the `repository` to resolve the dependency to the\n[SetaPDF-Signer](https://www.setasign.com/signer) component\n(see [here](https://getcomposer.org/doc/faqs/why-can%27t-composer-load-repositories-recursively.md) for more details).\n\n## Usage\n\nAll classes in this package are located in the namespace `setasign\\SetaPDF\\Signer\\Module\\SAFE`. See the [examples/](examples/) folder for\nworking examples.\n\n### The `Client` class\n\nThis class is a kind of proxy class to the SAFE API. Its constructor requires the following arguments:\n\n- `$apiUri` The base url of the api e.g. `https://pprsafe.autenticacao.gov.pt`\n- `$basicAuthUsername` The username for HTTP Basic authentiaction\n- `$basicAuthPassword` The password for HTTP Basic authentiaction\n- `$httpClient` PSR-18 HTTP Client implementation.\n- `$requestFactory` PSR-17 HTTP Factory implementation.\n- `$streamFactory` PSR-17 HTTP Factory implementation.\n\nIf you need to call an endpoint which is not covered by a proxy method, you can use the `call(string $path, ?string $accessToken = null, array $inputData = [])` method.\n\n### The `Module` class\n\nThis is the main module for the SetaPDF-Signer which implements the\n[`SetaPDF_Signer_Signature_Module_ModuleInterface`](https://manuals.setasign.com/api-reference/setapdf/c/SetaPDF.Signer.Signature.Module.ModuleInterface) interface.\n\nInternally it creates PAdES conforming signatures by using the [`SetaPDF_Signer_Signature_Module_PadesProxyTrait`](https://manuals.setasign.com/api-reference/setapdf/c/SetaPDF.Signer.Signature.Module.PadesProxyTrait).\n\nIts constructor requires the following arguments:\n\n- `$accessToken` - The access token which is passed with the custom header SAFEAuthorization.\n- `$client` - An instance of the `Client` class.\n- `$credentialId` - The id of the credentials (can be received as demoed in [list-credentials.php](examples/list-credentials.php))\n- `$processId` - A process id (a new Globally Unique Identifier (GUID) for each invocation).\n- `$clientName` - The value for the clientName field.\n\nAdditionally, the module offers a `setDocumentName()` method. This method allows you to define the document name related\nto the hash send to the SAFE API. By default, the document name is set to \"document.pdf\".\n\n### The `Batch` class\n\nThis class allows you to digital sign several PDF files in a single signature flow.\n\nIts constructor requires the following arguments:\n\n- `$accessToken` - The access token which is passed with the custom header SAFEAuthorization.\n- `$client` - An instance of the `Client` class.\n- `$credentialId` - The id of the credentials (can be received as demoed in [list-credentials.php](examples/list-credentials.php))\n- `$processId` - A process id (a new Globally Unique Identifier (GUID) for each invocation).\n- `$clientName` - The value for the clientName field.\n\nYou can pass several files as an array to the `sign($files)` method:\n\n```php\n$files = [\n    [\n        'in' =\u003e string|SetaPDF_Core_Reader_ReaderInterface,\n        'out' =\u003e 'path/to/result.pdf'    \n    ]   \n];\n```\n\nAdditionally, the `sign()` method accepts callbacks to e.g. add individual signature \nappearances or signature properties. For an example see the [batch-complex.php](examples/batch-complex.php) demo.\n\n## License\n\nThis package is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsetasign%2Fsetapdf-signer-addon-safe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsetasign%2Fsetapdf-signer-addon-safe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsetasign%2Fsetapdf-signer-addon-safe/lists"}