typhonius / acquia-php-sdk-v2 Goto Github PK

Add Symfony 6 support

This commit a301ebd has broken windows compatibility by calling posix_getpwuid(), which apparently does not exist in PHP on Windows.

A new feature of Acquia Cloud platform has been released: Platform Email service.
This is a new feature that incorporates some new API responses/actions to view/control the service.

It would be good to incorporate the new endpoints into the SDK

• http://cloudapi-docs.acquia.com/#/Applications/getApplicationEmailDomains
• http://cloudapi-docs.acquia.com/#/Applications/postApplicationAssociateEmailDomain
• http://cloudapi-docs.acquia.com/#/Applications/postApplicationDisassociateEmailDomain
• http://cloudapi-docs.acquia.com/#/Environments/postEnvironmentEmailDisable
• http://cloudapi-docs.acquia.com/#/Environments/postEnvironmentEmailEnable
• http://cloudapi-docs.acquia.com/#/Email/getEmailStatus
• http://cloudapi-docs.acquia.com/#/Subscriptions/getSubscriptionDomainRegistrations
• http://cloudapi-docs.acquia.com/#/Subscriptions/postSubscriptionDomainRegistration
• http://cloudapi-docs.acquia.com/#/Subscriptions/getSubscriptionDomainRegistration
• http://cloudapi-docs.acquia.com/#/Subscriptions/deleteSubscriptionDomainRegistration
• http://cloudapi-docs.acquia.com/#/Subscriptions/postSubscriptionVerifyDomainRegistration

Since the platform email service touches Subscriptions (registering domains), Applications (associating domains), and Environments (enabling the service), I'm not sure if it would be preferable to have "Emails" as an Endpoint/Response set or simply fold them into the existing objects.

PHP 7.4 has been EOL for a while now, we should consider dropping support for it including removing it from composer.json, removing it from test workflows, and removing it from required status checks.

Are there plans for a 1.0.3 release in the forseeable future? BLT previously required this package at ^1.0.2 and we would benefit from bugfixes that have been pushed to the master branch but are not yet available in a stable release on packagist.

https://cloudapi-docs.acquia.com/#/Environments/getEnvironmentsDatabaseDownloadBackup

The purge function of Domain is using
"/environments/${environmentUuid}/domains/actions/clear-varnish"
which is deprecated (http://cloudapi-docs.acquia.com/). Today I noticed that although it states "___ executed varnish cleared" in the event log of the cloud UI, this does not seem to actually clear varnish anymore. When done manually, the report log states "___ executed Clearing caches"
The endpoint for clearing caches is:
/environments/{environmentId}/actions/clear-caches

Is your feature request related to a problem? Please describe.
The /account/ides endpoint allows you to get all IDEs belonging to your account. Customers find this really useful, so Acquia CLI is exposing it as a command. It would be nice to access it idiomatically via an Endpoint. See acquia/cli#712

Describe the solution you'd like
New method added to either the Account or Ides endpoint. Account::getIdes() matches the API structure and sounds better, but Ides::getMine() groups it a little more logically. Not sure which to use.

Describe alternatives you've considered
Constructing a request ourselves as in acquia/cli#712, which is fine but impairs static analysis, code completion, and readability.

Integer value submitted to Environments->update() endpoint and incorrectly cast to string.

E.g.,

$env = new Environments($acquia_cloud_client);
$env->update('[my uuid]', ['memory_limit' => 192]);

Results in:

{
    "error": "validation_failed",
    "message": {
        "memory_limit": "192 is not a valid memory limit. It should be an integer."
    }
}

Describe the bug
The makeRequest() method on src/CloudApi/Connector.php does not check if the access token has expired.

To Reproduce

1. In a long running process, setup an access token
2. Call makeRequest()
3. Wait 5 minutes
4. Call makeRequest() again
5. Notice an exception is thrown with a 403 Forbidden response from the API:

{
    "error": "unauthorized",
    "message": "The access token has expired."
}

Expected behavior
When a request is made the second time, a check is made if the token is expired. If it is expired, get a new one.

Screenshots
NA

Desktop (please complete the following information):

• OS: Ubuntu
• Code version/tag: 1.1.1

Additional context
#48 seems related.

This issue is fixed in the latest, see: https://github.com/typhonius/acquia-php-sdk-v2/blob/master/src/Connector/Connector.php#L59

This issue will be expired currently by anyone using https://github.com/lcatlett/blt-drush-alias/blob/master/composer.json#L15 because it locks this library to v1.

When using the update() method in crons.php, I get the following error:
"The method "post" is not available for the resource "api/environments/xxxxxx-xxxx-xxxx-xxxx/crons/yyyyy-yyyy-yyyyy-yyyyy"

As per the documentation it should be PUT instead of POST to edit existing cron task.
https://cloudapi-docs.acquia.com/#/Environments/putCron

When attempting to delete a database:

[error]  The method "post" is not available for the resource "api/applications/[redacted]/databases/[db-name]".

I noticed in the docs that it expects a DEL request, so I changed it to that, but I still get an error. Maybe it's a bug in their API?

Describe the bug
See here where the EnvironmentResponse object maps the id field in the response to the uuid field on the object. This prohibits the EnvironmentResponse from being validated successfully against the Cloud Api OpenAPI spec.

I've been using thephpleague/openapi-psr7-validator to validate locally stored and altered objects initially retrieved from Cloud API objects. I want to use this library to homogenise my local data and data that comes via typhonius/acquia-php-sdk-v2 so my functions can use both without excessive conditions to handle the data based on its source. Instead, I can validate the data through the OpenApi Spec, then trust it.

To Reproduce
Here is an example:

use cebe\openapi\Reader;
use cebe\openapi\ReferenceContext;
use cebe\openapi\spec\Reference;
use cebe\openapi\SpecObjectInterface;
use League\OpenAPIValidation\Schema\SchemaValidator;

// ...
    const SpecUrl = 'https://cloudapi-docs.acquia.com/acquia-spec.yaml';
    protected SpecObjectInterface $spec;

    public function validate(array|object $response, string $ref) {
        $response = (array) $response;
         // e.g. #/component/schema/Environment.
        $response['$ref'] = $ref;
        $reference = new Reference($response);
        $context = new ReferenceContext($this->spec, self::SpecUrl);
        $schema = $reference->resolve($context);
        $validator = new SchemaValidator();
       // Throw exception because id property is missing on Environment.
        $validator->validate($response, $schema);
        return true;
    }

Hey @typhonius , you mentioned that you weren't working with this project (or indeed, PHP) much lately. Would you consider giving push access to @grasmash and myself to help with maintenance? We'd treat it like any other Acquia project and make sure that PRs go through a thorough review process before merging, and follow your lead on any other best practices.

When deploying new code to production and staging I first create a DB backup through the API (thanks for this library which makes doing that much easier!) Unfortunately over time those backups pile up and are no longer needed.

It would be great if the library supported deleting database backups. There is a API endpoint available for this: https://cloudapi-docs.acquia.com/#/Environments/deleteEnvironmentsDatabaseBackup

Right now I have to manually delete backups, but if this feature was added it could be automated as part of my deployment process..

#137 was supposed to allow testing against non-production Cloud API endpoints, but I suspect it never worked as intended because the Connector OAuth client will still use the production Accounts endpoint, making it impossible to authenticate against the stage API.

DatabaseBackups::download() returns a stream resource, therefore I would expect it to not load the entire db backup into memory, but rather return a stream that can be written to disk. However, in practice memory usage appears to match the size of a given db backup. This obviously causes a problem if your db backup is larger than your PHP memory limit.

$database_backups = new DatabaseBackups($acquia_cloud_client);
$database_backups->download($environment->uuid, $database->name, $backup_response->id); // huge memory usage here

The domain status endpoint has some additional information that could be useful like dns_resolves and acquia_hosted flags. It would be nice to have another method to process these responses.

https://cloudapi-docs.acquia.com/#/Environments/getEnvironmentsDomainStatus

There is an API endpoint for /account/applications/{applicationUuid}/has-permission which returns basically true or false if the account has access to a specific permission on a specific application.

Should this be a method in Account? Or in Permissions? Or… It doesn't really return an operation result, but an access response… Do we need a new AccessResponse class? Might be useful as there are other has-permission endpoints as well /account/teams/{teamUuid}/has-permission but those seem to be the only two.

They're both on the Account stub but might be more appropriate under Applications and Teams Endpoints respectively.

So before working on a PR, I figured I'd set a direction first.

When using the API directly, each endpoint will return a lot of information on the current request's result, including other endpoints should we require more information. This is useful for things like waiting for a database backup to be complete.

As it is, this library a simple message, without any additional info the API would normally provide.

Is this an intended limitation? If so, how would one wait for a given task to finish before moving on to something else?

Describe the bug
The point of an interface is to define how to interact with objects constructed by different class definitions so that code can interact with injected dependencies without needing to know exactly what they are or where they came from.

Given the SDK doesn't use the Connector __construct anywhere - do we need to define it in the ConnectorInterface? All this seems to do is limit how ConnectorInterface instances can be instantiated.

Describe the bug
Installing via Composer throws a warning:

Package webmozart/path-util is abandoned, you should avoid using it. Use symfony/filesystem instead.

We should replace that package

See recent runs: https://github.com/typhonius/acquia-php-sdk-v2/actions

Looks like a codecov token possibly expired. @typhonius you are probably the only person with access to fix that.

Is your feature request related to a problem? Please describe.
Currently, Cloud API requests from Acquia PHP SDK have a generic, default user agent string provided by Guzzle, i.e. GuzzleHttp/6.5.4 curl/7.68.0 PHP/7.4.3. This makes it difficult to monitor and debug failing requests from the server side, and trace them back to projects using Acquia PHP SDK.

Describe the solution you'd like
A unique identifier prepended to the user agent string, such as acquia-php-sdk-v2, and/or the ability for downstream projects to set their own user agent string.

Describe alternatives you've considered
I can't think of any. The current string isn't unique enough on its own to be useful, and there's no way I can see to override it from a downstream/consuming project.

If you want a more extensive solution, though, you could expose all of the headers to modification by consuming projects, not just the user-agent.

Additional context
I'm happy to help with a PR if you can let me know what approach you prefer. Thanks!

Describe the bug
SslCertificates endpoint for enabling/disabling certificate is not correct.
Acquia Cloud API Endpoint has to be /environments/${uuid}/ssl/certificates/...

To Reproduce
When calling enable or disable function, following message is displayed :

[error] The path "api/environments/XXX/ssl/certificate/1234/actions/activate" does not match any known resources.

Expected behavior
Certificate should be activated/desactivated witthout error.

I'm using dev-master#8dfd3df

I've initialized my Cloud API client like so:

$cloud_api = Client::factory(array(
  'key' => $key,
  'secret' => $secret,
));

No problems with that. But when I try to call the API, such as $cloud_api->applications();, I get the following exception:

Response is missing required X-Server-Authorization-HMAC-SHA256 header.

I'm getting the following error when trying to catch an exception thrown as a the result of a 400. In this case, attempting to create a database that already exists.

try {
  $cloud->databaseCreate($application->uuid, $db);
} catch (\Exception $e) {
    // Log something.
}

Client error: `POST https://cloud.acquia.com/api/applications/xxx/databases` resulted in a `400 Bad Request` response:
{
    "error": "validation_failed",
    "message": {
        "name": "A database with that name already exists. Please c (truncated...)

Is there a way to hide that JSON output?

Fatal error: Uncaught Error: Wrong parameters for Exception([string $message [, long $code [, Throwable $previous = NULL]]]) in vendor/typhonius/acquia-php-sdk-v2/src/CloudApi/Connector.php on line 119

Is this possible or am I supposed to code around these? Thanks!

Currently this package doesn't have tests - it would be great to have each of the methods used to talk to the API tested in a way that adheres to expected responses from the API and prevents breakage in future.

Describe the bug
User agent strings are applied multiple times because the addOption keeps applying them on subsequent queries.

To Reproduce
Steps to reproduce the behavior including calling code:

1. Run the db:backup:list command using Acquia Cli
2. Dump the user agent headers
3. See a string containing multiple instances of each user agent

Expected behavior
A single user agent string for each library in use.

It would be nice if there was a way to call the account endpoint. It doesn't seem like this is possible now. This could be a dedicated account method, or a method that lets you call arbitrary endpoints that might not yet be supported by this package.

My use case isn't really to get account info, but to check that authentication was successful. I've been told that calling account is significantly less expensive than calling other methods like applications.

I've been trying to use cgr to install acquia_cli, but my version of phpcbf and phpcs keeps getting clobbered by the version this library is using. I don't think Acquia requires you to use codesniffer to use it, so I would suggest moving it if possible.

The HMAC authentication process is deprecated from Cloud API v2.

All of the documentation points to using an OAuth 2.0 token process.

I know you can get the same information returned from Client::domains but in the context of an EnvironmentResponse, it would be nice to get info about one of the domains in the domains property.

Is your feature request related to a problem? Please describe.
Token is expiring after 300 seconds. This is expected as per acquia docs: https://docs.acquia.com/acquia-cloud/develop/api/auth/

The API token will expire 300 seconds (or 5 minutes) after you generate it and must be regenerated before then.

This is failing with exception message: The access token has expired.

Describe the solution you'd like
Connector should be able to auto regenerate the auth token after that time is past.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Describe the bug
As an example, the environment->update() method should take values like ['memory_limit' => 192], however, the API returns:

PHP Fatal error:  Uncaught AcquiaCloudApi\Exception\ApiErrorException: [0]: 192 is not a valid memory limit. It should be an integer.

This is because x-www-form-urlencoded is not typed and everything comes through as a string. I am trying to track down any documentation on this on Acquia's side, but confirmed with the API team last year about boolean values.

To Reproduce

$environment = new Environments($client);
$environmentUuid = '<REDACTED>';
$config = [
  'memory_limit' => 152,
];

$environment->update($environmentUuid, $config);

Expected behavior
I expect that it succeeds.

Is your feature request related to a problem? Please describe.
Some endpoints return a Notification UUID to allow for tracking the completion of an attempt.
For example, when you create a database backup or ask to purge Varnish cache, the response is that the process has started and a Notification to track.

However, the json body response only has a "_links.notification.href" with a full URL to the notification. To use the "Notifications" object directly, you need to have a notification UUID. In the body response, this would involve parsing the href URL to extract the ID.

There is also an HTTP header, X-CloudApi-Notification-Id, that is returned with just the ID which would be helpful.

Describe the solution you'd like
It seems that having the ability to a) retrieve the UUID directly and b) have a semi-automated looping mechanism that can track the notification to "completed" or an error state.