PHPackages openeuropa/epoetry-client - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. openeuropa/epoetry-client ActiveLibrary[API Development](/categories/api) openeuropa/epoetry-client ========================= PHP client for the ePoetry service. 4.x-dev(7mo ago)145.7k↓30.2%4[3 issues](https://github.com/openeuropa/epoetry-client/issues)[2 PRs](https://github.com/openeuropa/epoetry-client/pulls)1EUPL-1.2PHPPHP >=8.3CI passing Since Jul 2Pushed 1mo ago11 watchersCompare [ Source](https://github.com/openeuropa/epoetry-client)[ Packagist](https://packagist.org/packages/openeuropa/epoetry-client)[ RSS](/packages/openeuropa-epoetry-client/feed)WikiDiscussions 4.x Synced 1mo ago READMEChangelog (7)Dependencies (34)Versions (24)Used By (1) ePoetry PHP client ================== [](#epoetry-php-client) PHP client for the ePoetry service. Before proceeding, it is recommended to read the ["Introduction and terminology"](https://citnet.tech.ec.europa.eu/CITnet/confluence/pages/viewpage.action?pageId=967905830)section of the official [ePoetry documentation](https://citnet.tech.ec.europa.eu/CITnet/confluence/display/EPOETRY/ePoetry+webservices). A bird's-eye overview of a typical translation request workflow can be outlined as follows: - The web application (e.g. a Drupal site) creates a translation request onto the ePoetry service, by making a SOAP method call - The ePoetry service synchronously answers such a call with either a response object, or an error - The translation request is manually processed by DGT backoffice, this can take several days - Once completed, the ePoetry service sends a notification to the web application, via a SOAP method call, which contains the requested translations This project provides the necessary code (SOAP objects, middleware, etc.) to request a translation and handle incoming notifications from the ePoetry service. Versions -------- [](#versions) - 4.x should be used with PHP > 8.3 and Symfony 7.x - 3.x should be used with PHP > 8.3 and Symfony 6.x - 2.x should be used with PHP > 8.1.26 and Symfony 5.x, or 6.x - 1.x should be used with PHP 8.0 and Symfony 4.x Project overview ---------------- [](#project-overview) - [`./bin/epoetry`](./bin/epoetry): CLI executable to interact with the ePoetry service - [`./resources`](./resources): request and notification services WSLD/XLD files, as provided by the ePoetry service. Original resources can be obtained by accessing the following links, withing the European Commission network: - Request service WSDL: - Request service XSD: - Notification service WSDL: - Notification service XSD: - [`./config/soap-client-*.php`](./config): configuration files for the code generation - [`./config/validator/*.yaml`](./config/validator): configuration files for object validation, built using [Symfony Validator](https://symfony.com/doc/4.4/validation.html) - [`./src/CodeGenerator`](./src/CodeGenerator): set of assembler classes, used to generated client's code - [`./src/Console`](./src/Console): Symfony Console command classes - [`./src/ExtSoapEngine`](./src/ExtSoapEngine): custom SOAP engine classes, such as a WSDL provider to process locally stored WSDL files - [`./src/Notification`](./src/Notification): automatically generated classes for the "Notification" service - [`./src/Request`](./src/Request): automatically generated classes for the "Request" service - [`./src/Authentication`](./src/Authentication): authentication services - [`./src/TicketValidation`](./src/TicketValidation): ticket validation services Authentication -------------- [](#authentication) The ePoetry service uses EU Login as a trusted third-party authentication system. Application that wants to use the ePoetry client will need to request an EU Login Job Account. You can request an EU Login job account from DIGIT by visiting [this page](https://intracomm.ec.testa.eu/itservices/eu-login_en)and communicate it to DGT for setting up access. When requesting your job account, please keep in mind that: - ePoetry test environment uses EU Login acceptance - ePoetry staging and production environment uses EU Login production **Note:** when requesting your job account make sure to ask DIGIT to insert your DG in the job account's "department" field: this is required by the ePoetry service. Once you get your job account, you have two ways of authenticating against the service: - Via Client Certificate login - Via OpenID Connect **PLEASE NOTE:** both methods above requires extra dependencies to be added to your project, please check the respective sections below for more information. ### Authenticating via Client Certificate login [](#authenticating-via-client-certificate-login) In EU Login, the application running the ePoetry library (e.g. a Drupal site) can be represented by a special kind of user accounts called a "job account". In order to set up this authentication method you need to request a job account to EU Login, linked to the site running the ePoetry library. You can ask your direct manager or scrum master to initiate the request job account request. Check [this page](https://citnet.tech.ec.europa.eu/CITnet/confluence/pages/viewpage.action?spaceKey=IAM&title=ECAS+Certificate+Login) for more information. After getting an EU Login job account you need to communicate this to DGT so that they can proceed with the setup on the ePoetry service. For more information about this procedure check [this page](https://citnet.tech.ec.europa.eu/CITnet/confluence/display/EPOETRY/2.+New+client+system). Once you get the job account you need to request a client certificate: you can ask this too to your scum master. On acceptance environments you can request one yourself at . Once you receive the actual client certificate file, in `.p12` format, and its password, you can configure the authentication plugin service. Below an example of a possible setup: ``` client_cert_authentication: class: \OpenEuropa\EPoetry\Authentication\ClientCertificate\ClientCertificateAuthentication arguments: $serviceUrl: "https://www.cc.cec/epoetry/webservices/dgtService" $certFilepath: "/path/to/certs/j123abc.p12" $certPassword: "password" $euLoginBasePath: "https://ecas.cc.cec.eu.int:7003" $logger: "..." # A PSR compatible logger implementation. ``` For ePoetry acceptance, use the following: ``` $serviceUrl: "https://www.acceptance.cc.cec/epoetry/webservices/dgtService" ``` **PLEASE NOTE:** this authentication method requires the following dependencies, as specified in `composer.json` "suggest" section: ``` "suggest": { "symfony/http-client": "Require this in your project if you use the client certificate authentication plugin." }, ``` ### Authenticating via OpenID Connect [](#authenticating-via-openid-connect) You can authenticate using OpenID Connect by using the [OpenIDAuthentication](./src/Authentication/OpenID/OpenIDAuthentication.php)plugin. This authentication plugin needs the following parameters to be set: - The OpenID Connect ".well-known" endpoint URL of the target environment, be it acceptance or production. Possible values are: - Acceptance: - Production: - The ePoetry service URL endpoint you want to target. You can use the following: - Test: or its publicly accessible proxy - Acceptance: - Production: - EU Login token endpoint: - Acceptance: - Production: - The location of a client metadata JSON file. In order to obtain this you need to register your application as an OpenID Connect client by following [these instructions](https://citnet.tech.ec.europa.eu/CITnet/confluence/display/IAM/OpenID+Connect+-+Client+Registration). Below you can find a working example of a client metadata: ``` { "application_type" : "web", "client_id" : "...", "client_id_issued_at" : 1656329142, "client_name" : "[Name of your application]", "client_secret" : "...", "client_secret_expires_at" : 0, "client_type" : "confidential", "contacts" : [ "[Email of the EC official issuing the request]" ], "grant_types" : [ "client_credentials" ], "id_token_signed_response_alg" : "PS512", "job_account" : "[Your EU Login Job Account ID]", "oauth_application_type" : "web_application", "redirect_uris" : [ "[Your application's URL]" ], "registration_access_token" : "...", "registration_client_uri" : "...", "response_types" : [ ], "scope" : "openid", "subject_type" : "public", "token_endpoint_auth_method" : "client_secret_jwt" } ``` Use the above values as a reference to configure your own client metadata. Make sure you set these as follows: ``` ... "application_type" : "web", "grant_types" : [ "client_credentials" ], "id_token_signed_response_alg" : "PS512", "oauth_application_type" : "web_application", "token_endpoint_auth_method" : "client_secret_jwt" ... ``` Once you get such information, store it in a JSON file that is reachable by your application, as this will be needed to configure the authentication service. Below an example of a possible setup: ``` openid_authentication: class: \OpenEuropa\EPoetry\Authentication\OpenID\OpenIDAuthentication arguments: $wellKnownUrl: "https://ecas.ec.europa.eu/cas/oauth2/.well-known/openid-configuration" $clientMetadataFilepath: "/path/to/client-metadata.json" $serviceUrl: "https://www.cc.cec/epoetry/webservices/dgtService" $tokenEndpoint: "https://ecas.ec.europa.eu/cas/oauth2/token" $logger: "..." # A PSR compatible logger implementation. ``` For ePoetry acceptance, use the following: ``` $serviceUrl: "https://www.acceptance.cc.cec/epoetry/webservices/dgtService" ``` **PLEASE NOTE:** this authentication method requires the following dependencies, as specified in `composer.json` "suggest" section: ``` "suggest": { "facile-it/php-openid-client": "Require this in your project if you use the OpenID Connect authentication plugin.", "web-token/jwt-signature-algorithm-hmac": "Require this in your project if you use the OpenID Connect authentication plugin.", }, ``` ePoetry Notifications --------------------- [](#epoetry-notifications) The ePoetry service sends messages to the site, containing information about a translation request status change, the translated content, etc. In order for your application to be able to receive and handle ePoetry notifications, you need to expose two endpoints: - One that provides the site's WSDL to the ePoetry service. - One that handles POST inbound requests, coming from the ePoetry service. The [`NotificationServerFactory`](./src/NotificationServerFactory.php) can be used in implementing both endpoints. The `NotificationServerFactory` service requires the following dependencies: - `$callback`: the site's endpoint handing inbound POST requests. - `$eventDispatcher`: a Symfony event dispatcher instance. - `$logger`: a PSR compatible logger implementation. - `$serializer`: an instance of the library's [Serializer class](./src/Serializer/Serializer.php) - `$ticketValidation`: optionally, an instance of the [ticket validation service](./src/TicketValidation/TicketValidationInterface.php). Below an example of a Symfony controller that implements both endpoints: ```