SM-1402 - review and update php sdk

languages/php/INSTALL.md

@@ -0,0 +1,56 @@
+# PHP Installation
+
+## Introduction
+
+Composer is used to build the PHP Bitwarden client library.
+
+## Prerequisites
+
+- PHP >= 8.0
+- FFI extension enabled in PHP configuration
+- Composer
+- Bitwarden SDK native library.
+  - Expected in one of below locations, depending on the OS and architecture.
+    The `src` is relative path to the [src](./src) directory.
+    - Windows x86_64: `src\lib\windows-x64\bitwarden_c.dll`
+    - Linux x86_64: `src/lib/linux-x64/libbitwarden_c.so`
+    - macOS x86_64: `src/lib/macos-x64/libbitwarden_c.dylib`
+    - macOS aarch64: `src/lib/macos-arm64/libbitwarden_c.dylib`
+  - If you prefer to build the SDK yourself, see the [SDK README.md](../../README.md) for instructions.
+
+## Build Commands
+
+```shell
+composer install
+```
+
+## Example
+
+### macOS
+
+#### Install Prerequisites
+
+Use brew Composer and PHP
+
+```shell
+brew install php
+brew install composer
+```
+
+#### Build Commands
+
+```shell
+composer install
+```
+
+## Example SDK Usage Project
+
+```shell
+export ACCESS_TOKEN="<access_token>"
+export STATE_FILE="<state_file>"
+export ORGANIZATION_ID="<organization_id>"
+export API_URL="https://api.bitwarden.com"
+export IDENTITY_URL="https://identity.bitwarden.com"
+
+php example.php
+```

languages/php/README.md

@@ -1,100 +1,120 @@
 # Bitwarden Secrets Manager SDK wrapper for PHP
 
 PHP bindings for interacting with the [Bitwarden Secrets Manager]. This is a beta release and might be missing some functionality.
-Supported are CRUD operations on project and secret entities.
 
 ## Installation
 
-Requirements:
-- PHP >= 8.0
-- Composer
-- Bitwarden C libraries which you can generate using BitwardenSDK and following instructions in its readme (requires Rust). https://github.com/bitwarden/sdk
-If you are not using the standalone version of this library, file will be placed in `target/debug` folder if you are using from BitwardenSDK repository.
-- Access token for the Bitwarden account
-
+See the [installation instructions](./INSTALL.md)
 
 ## Usage
 
-To interact with the client first you need to obtain the access token from Bitwarden.
-You can then initialize BitwardenSettings passing $api_url and $identity_url if needed. These parameteres are
-optional and if they are not defined, BitwardenSettings instance will try to get these values from ENV, and
-if they are not defined there as well, it will use defaults: `https://api.bitwarden.com` as api_url and
-`https://identity.bitwarden.com` as identity_url. You can also pass device type as argument but that is entirely
-optional.
+### Create access token
 
-Passing BitwardenSettings instance to BitwardenClient will initialize it. Before using the client you must
-be authorized by calling the access_token_login method passing your Bitwarden access token to it.
+To interact with the client first you need to obtain the access token from Bitwarden.
+Review the help documentation on [Access Tokens].
 
+### Create new Bitwarden client
 
 ```php
-$access_token = '<your token here>';
-$api_url = "<api url>";
-$identity_url = "<identity url>";
+require_once 'vendor/autoload.php';
+
+$access_token = "<access-token>";
+$organization_id = "<organization-id>";
+$api_url = "https://api.bitwarden.com";
+$identity_url = "https://identity.bitwarden.com";
+
 $bitwarden_settings = new \Bitwarden\Sdk\BitwardenSettings($api_url, $identity_url);
 
 $bitwarden_client = new \Bitwarden\Sdk\BitwardenClient($bitwarden_settings);
-$bitwarden_client->access_token_login($access_token);
+$bitwarden_client->auth->login_access_token($access_token, $state_file);
 ```
 
-After successful authorization you can interact with client to manage your projects and secrets.
-```php
-$organization_id = "<your organization id here>";
+Initialize `BitwardenSettings` by passing `$api_url` and `$identity_url` or set to null to use the defaults.
+The default for `api_url` is `https://api.bitwarden.com` and for `identity_url` is `https://identity.bitwarden.com`.
 
-$bitwarden_client = new \Bitwarden\Sdk\BitwardenClient($bitwarden_settings);
-$res = $bitwarden_client->access_token_login($access_token);
+### Create new project
 
-// create project
-$name = "PHP project"
-$res = $bitwarden_client->projects->create($name, $organization_id);
+```php
+$name = "PHP project";
+$res = $bitwarden_client->projects->create($organization_id, $name);
 $project_id = $res->id;
+```
 
-// get project
+### Get project
+
+```php
 $res = $bitwarden_client->projects->get($project_id);
+```
+
+### List all projects
 
-// list projects
+```php
 $res = $bitwarden_client->projects->list($organization_id);
+```
 
-// update project
-$name = "Updated PHP project"
-$res = $bitwarden_client->projects->put($project_id, $name, $organization_id);
+### Update project
 
-// get secret
-$res = $bitwarden_client->secrets->get($secret_id);
+```php
+$name = "Updated PHP project";
+$res = $bitwarden_client->projects->update($organization_id, $project_id, $name);
+```
 
-// list secrets
-$res = $bitwarden_client->secrets->list($organization_id);
+### Delete project
 
-// delete project
+```php
 $res = $bitwarden_client->projects->delete([$project_id]);
+```
 
+### Create new secret
+
+```php
+$key = "Secret key";
+$note = "Secret note";
+$value = "Secret value";
+$res = $bitwarden_client->secrets->create($organization_id, $key, $value, $note, [$project_id]);
+$secret_id = $res->id;
 ```
 
-Similarly, you interact with secrets:
+### Get secret
+
 ```php
-$organization_id = "<your organization id here>";
+$res = $bitwarden_client->secrets->get($secret_id);
+```
 
-// create secret
-$key = "AWS secret key";
-$note = "Private account";
-$secret = "76asaj,Is_)"
-$res = $bitwarden_client->secrets->create($key, $note, $organization_id, [$project_id], $secret);
-$secret_id = $res->id;
+### Get multiple secrets
 
-// get secret
-$res = $bitwarden_sdk->secrets->get($secret_id);
+```php
+$res = $bitwarden_client->secrets->get_by_ids([$secret_id]);
+```
 
-// list secrets
+### List all secrets
+
+```php
 $res = $bitwarden_client->secrets->list($organization_id);
+```
+
+### Update secret
+
+```php
+$key = "Updated key";
+$note = "Updated note";
+$value = "Updated value";
+$res = $bitwarden_client->secrets->update($organization_id, $secret_id, $key, $value, $note, [$project_id]);
+```
 
-// update secret
-$note = "Updated account";
-$key = "AWS private updated"
-$secret = "7uYTE,:Aer"
-$res = $bitwarden_client->secrets->update($secret_id, $key, $note, $organization_id, [$project_id], $secret);
+### Sync secrets
 
-// delete secret
-$res = $bitwarden_sdk->secrets->delete([$secret_id]);
+```php
+$last_synced_date = "2024-09-01T00:00:00Z";
+$res = $bitwarden_client->secrets->sync($organization_id, $last_synced_date);
+```
+
+### Delete secret
+
+```php
+$res = $bitwarden_client->secrets->delete([$secret_id]);
 ```
 
+[Access Tokens]: https://bitwarden.com/help/access-tokens/
 
 [Bitwarden Secrets Manager]: https://bitwarden.com/products/secrets-manager/

languages/php/example.php

@@ -3,6 +3,7 @@
 require_once 'vendor/autoload.php';
 
 $access_token = getenv('ACCESS_TOKEN');
+$state_file = getenv('STATE_FILE');
 $organization_id = getenv('ORGANIZATION_ID');
 
 // Configuring the URLS is optional, set them to null to use the default values
@@ -12,36 +13,89 @@
 $client_settings = new \Bitwarden\Sdk\BitwardenSettings($api_url, $identity_url);
 
 $bitwarden_client = new \Bitwarden\Sdk\BitwardenClient($client_settings);
-$bitwarden_client->access_token_login($access_token);
+try {
+    $bitwarden_client->auth->login_access_token($access_token, $state_file);
+} catch (Exception $e) {
+    print("Error: " . $e->getMessage() . "\n");
+    exit(1);
+}
 
 // create project
-$res = $bitwarden_client->projects->create('php project', $organization_id);
+print("Projects:\n");
+$res = $bitwarden_client->projects->create($organization_id, 'php project');
 $project_id = $res->id;
+print("\tcreate: '" . $project_id . "'\n\n");
 
 // get project
 $res = $bitwarden_client->projects->get($project_id);
+print("\tget: '" . $res->name . "'\n\n");
 
 // list projects
 $res = $bitwarden_client->projects->list($organization_id);
+print("\tlist:\n");
+foreach ($res->data as $project) {
+    print("\t\tID: '" . $project->id . "', Name: '" . $project->name . "'\n");
+}
+print("\n");
 
 // update project
-$res = $bitwarden_client->projects->put($project_id, 'php test awesome', $organization_id);
+$res = $bitwarden_client->projects->update($organization_id, $project_id, 'php test awesome');
+print("\tupdate: '" . $res->name . "'\n\n");
+
+// sync secrets
+print("Secrets:\n");
+print("\tSyncing secrets...\n");
+$res = $bitwarden_client->secrets->sync($organization_id,null);
+$now = new DateTime();
+$now_string = $now->format('Y-m-d\TH:i:s.u\Z');
+print("\t\tSync has changes: " . ($res->hasChanges ? 'true' : 'false') . "\n\n");
+
+print("\tSyncing again to ensure no changes since last sync...\n");
+$res = $bitwarden_client->secrets->sync($organization_id, $now_string);
+print("\t\tSync has changes: " . ($res->hasChanges ? 'true' : 'false') . "\n\n");
 
 // create secret
-$res = $bitwarden_client->secrets->create("New Key", "hello world", $organization_id, [$project_id], "123");
+$res = $bitwarden_client->secrets->create($organization_id, "New Key", "New value", "New note", [$project_id]);
 $secret_id = $res->id;
+print("\tcreate: '" . $secret_id . "'\n\n");
 
 // get secret
 $res = $bitwarden_client->secrets->get($secret_id);
+print("\tget: '" . $res->key . "'\n\n");
+
+// get multiple secrets by ids
+$res = $bitwarden_client->secrets->get_by_ids([$secret_id]);
+print("\tget_by_ids:\n");
+foreach ($res->data as $secret) {
+    print("\t\tID: '" . $secret->id . "', Key: '" . $secret->key . "'\n");
+}
+print("\n");
 
 // list secrets
 $res = $bitwarden_client->secrets->list($organization_id);
+print("\tlist:\n");
+foreach ($res->data as $secret) {
+    print("\t\tID: '" . $secret->id . "', Key: '" . $secret->key . "'\n");
+}
+print("\n");
 
 // update secret
-$res = $bitwarden_client->secrets->update($secret_id, "hello world 2", "hello", $organization_id, [$project_id], "123");
+$res = $bitwarden_client->secrets->update($organization_id, $secret_id, "Updated key", "Updated value", "Updated note", [$project_id]);
+print("\tupdate: '" . $res->key . "'\n\n");
 
 // delete secret
+print("Cleaning up secrets and projects:\n");
 $res = $bitwarden_client->secrets->delete([$secret_id]);
+print("\tdelete:\n");
+foreach ($res->data as $secret) {
+    print("\t\tdeleted secret: '" . $secret->id . "'\n");
+}
+print("\n");
 
 // delete project
 $res = $bitwarden_client->projects->delete([$project_id]);
+print("\tdelete:\n");
+foreach ($res->data as $project) {
+    print("\t\tdeleted project: '" . $project->id . "'\n");
+}
+print("\n");