{"id":28547858,"url":"https://github.com/ydb-platform/ydb-php-sdk","last_synced_at":"2025-07-08T05:31:48.303Z","repository":{"id":39788621,"uuid":"357230524","full_name":"ydb-platform/ydb-php-sdk","owner":"ydb-platform","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-08T16:51:53.000Z","size":2001,"stargazers_count":33,"open_issues_count":124,"forks_count":16,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-06-10T01:07:51.783Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ydb-platform.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-12T14:45:12.000Z","updated_at":"2025-04-24T22:11:09.000Z","dependencies_parsed_at":"2023-09-25T07:51:20.635Z","dependency_job_id":"0d359d09-9c3f-45e6-af3c-a7f28e8c2eb4","html_url":"https://github.com/ydb-platform/ydb-php-sdk","commit_stats":{"total_commits":77,"total_committers":10,"mean_commits":7.7,"dds":"0.24675324675324672","last_synced_commit":"e2afccaee89787fa155a8e01fdce3096c7db69a9"},"previous_names":[],"tags_count":47,"template":false,"template_full_name":null,"purl":"pkg:github/ydb-platform/ydb-php-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ydb-platform%2Fydb-php-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ydb-platform%2Fydb-php-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ydb-platform%2Fydb-php-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ydb-platform%2Fydb-php-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ydb-platform","download_url":"https://codeload.github.com/ydb-platform/ydb-php-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ydb-platform%2Fydb-php-sdk/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264200789,"owners_count":23571835,"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":[],"created_at":"2025-06-10T01:07:54.368Z","updated_at":"2025-07-08T05:31:48.291Z","avatar_url":"https://github.com/ydb-platform.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"YDB PHP SDK provides access to [YDB](https://ydb.tech/) from PHP code.\n\nYDB is a open-source distributed fault-tolerant DBMS with high availability and scalability, strict consistency and ACID. An SQL dialect – YQL – is used for queries.\n\nYDB is available in several modes:\n\n- On-prem installation (is not supported by this SDK yet);\n- Serverless computing mode in YC (only performed operations are paid);\n- Dedicated instance mode in YC (dedicated computing resources are paid).\n\n# Documentation\n\n[https://ydb.tech/docs/](https://ydb.tech/docs/)\n\n# Installation\n\nThe recommended method of installing is Composer.\n\nRun the following:\n\n```bash\ncomposer require ydb-platform/ydb-php-sdk\n```\n\n# Connection\n\nFirst, create a database using [Yandex Cloud Console](https://cloud.yandex.com/docs/ydb/quickstart/create-db).\n\nYDB supports the following authentication methods:\n\n- Access token\n- OAuth token\n- JWT + private key\n- JWT + JSON file\n- Metadata URL\n- Anonymous\n\n## Access token\n\nUse your access token:\n\n```php\n\u003c?php\n\nuse YdbPlatform\\Ydb\\Ydb;\n\n$config = [\n\n    // Database path\n    'database'    =\u003e '/ru-central1/b1glxxxxxxxxxxxxxxxx/etn0xxxxxxxxxxxxxxxx',\n\n    // Database endpoint\n    'endpoint'    =\u003e 'ydb.serverless.yandexcloud.net:2135',\n\n    // Auto discovery (dedicated server only)\n    'discovery'   =\u003e false,\n\n    // IAM config\n    'iam_config'  =\u003e [\n        'root_cert_file' =\u003e './CA.pem', // Root CA file (dedicated server only!)\n\n        // Access token authentication\n        'access_token'    =\u003e 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',\n    ],\n];\n\n$ydb = new Ydb($config);\n```\nor:\n```php\n\u003c?php\n\nuse YdbPlatform\\Ydb\\Ydb;\nuse YdbPlatform\\Ydb\\Auth\\Implement\\AccessTokenAuthentication;\n\n$config = [\n\n    // Database path\n    'database'    =\u003e '/ru-central1/b1glxxxxxxxxxxxxxxxx/etn0xxxxxxxxxxxxxxxx',\n\n    // Database endpoint\n    'endpoint'    =\u003e 'ydb.serverless.yandexcloud.net:2135',\n\n    // Auto discovery (dedicated server only)\n    'discovery'   =\u003e false,\n\n    // IAM config\n    'iam_config'  =\u003e [\n        'root_cert_file' =\u003e './CA.pem', // Root CA file (dedicated server only!)\n    ],\n    \n    'credentials' =\u003e new AccessTokenAuthentication('AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA')\n];\n\n$ydb = new Ydb($config);\n```\n## OAuth token\n\nYou should obtain [a new OAuth token](https://cloud.yandex.com/docs/iam/concepts/authorization/oauth-token).\n\nUse your OAuth token:\n\n```php\n\u003c?php\n\nuse YdbPlatform\\Ydb\\Ydb;\n\n$config = [\n\n    // Database path\n    'database'    =\u003e '/ru-central1/b1glxxxxxxxxxxxxxxxx/etn0xxxxxxxxxxxxxxxx',\n\n    // Database endpoint\n    'endpoint'    =\u003e 'ydb.serverless.yandexcloud.net:2135',\n\n    // Auto discovery (dedicated server only)\n    'discovery'   =\u003e false,\n\n    // IAM config\n    'iam_config'  =\u003e [\n        'temp_dir'       =\u003e './tmp', // Temp directory\n        'root_cert_file' =\u003e './CA.pem', // Root CA file (dedicated server only!)\n\n        // OAuth token authentication\n        'oauth_token'    =\u003e 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',\n    ],\n];\n\n$ydb = new Ydb($config);\n```\n\nor\n```php\n\u003c?php\n\nuse YdbPlatform\\Ydb\\Ydb;\nuse YdbPlatform\\Ydb\\Auth\\Implement\\OAuthTokenAuthentication;\n\n$config = [\n\n    // Database path\n    'database'    =\u003e '/ru-central1/b1glxxxxxxxxxxxxxxxx/etn0xxxxxxxxxxxxxxxx',\n\n    // Database endpoint\n    'endpoint'    =\u003e 'ydb.serverless.yandexcloud.net:2135',\n\n    // Auto discovery (dedicated server only)\n    'discovery'   =\u003e false,\n\n    // IAM config\n    'iam_config'  =\u003e [\n        'temp_dir'       =\u003e './tmp', // Temp directory\n        'root_cert_file' =\u003e './CA.pem', // Root CA file (dedicated server only!)\n    ],\n    \n    'credentials' =\u003e new OAuthTokenAuthentication('AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA')\n];\n\n$ydb = new Ydb($config);\n```\n## JWT + private key\n\nCreate [a service account](https://cloud.yandex.com/docs/iam/operations/sa/create) with the `editor` role, then create a private key. Also you need a key ID and a service account ID.\n\nConnect to your database:\n\n```php\n\u003c?php\n\nuse YdbPlatform\\Ydb\\Ydb;\n\n$config = [\n    'database'    =\u003e '/ru-central1/b1glxxxxxxxxxxxxxxxx/etn0xxxxxxxxxxxxxxxx',\n    'endpoint'    =\u003e 'ydb.serverless.yandexcloud.net:2135',\n    'discovery'   =\u003e false,\n    'iam_config'  =\u003e [\n        'temp_dir'           =\u003e './tmp', // Temp directory\n        'root_cert_file'     =\u003e './CA.pem', // Root CA file (dedicated server only!)\n\n        // Private key authentication\n        'key_id'             =\u003e 'ajexxxxxxxxx',\n        'service_account_id' =\u003e 'ajeyyyyyyyyy',\n        'private_key_file'   =\u003e './private.key',\n    ],\n];\n\n$ydb = new Ydb($config);\n```\n\nor\n```php\n\u003c?php\n\nuse YdbPlatform\\Ydb\\Ydb;\nuse YdbPlatform\\Ydb\\Auth\\Implement\\JwtWithPrivateKeyAuthentication;\n\n$config = [\n    'database'    =\u003e '/ru-central1/b1glxxxxxxxxxxxxxxxx/etn0xxxxxxxxxxxxxxxx',\n    'endpoint'    =\u003e 'ydb.serverless.yandexcloud.net:2135',\n    'discovery'   =\u003e false,\n    'iam_config'  =\u003e [\n        'temp_dir'           =\u003e './tmp', // Temp directory\n        'root_cert_file'     =\u003e './CA.pem', // Root CA file (dedicated server only!)\n\n        // Private key authentication\n        'key_id'             =\u003e 'ajexxxxxxxxx',\n        'service_account_id' =\u003e 'ajeyyyyyyyyy',\n        'private_key_file'   =\u003e './private.key',\n    ],\n    \n    'credentials' =\u003e new JwtWithPrivateKeyAuthentication(\n        \"ajexxxxxxxxx\",\"ajeyyyyyyyyy\",'./private.key')\n        \n];\n\n$ydb = new Ydb($config);\n```\n## JWT + JSON file\n\nCreate [a service account](https://cloud.yandex.com/docs/iam/operations/sa/create) with the `editor` role.\n\nCreate a service account [JSON file](https://cloud.yandex.com/docs/iam/operations/iam-token/create-for-sa#via-cli), save it in your project as `sa_name.json`.\n\nConnect to your database:\n\n```php\n\u003c?php\n\nuse YdbPlatform\\Ydb\\Ydb;\n\n$config = [\n    'database'    =\u003e '/ru-central1/b1glxxxxxxxxxxxxxxxx/etn0xxxxxxxxxxxxxxxx',\n    'endpoint'    =\u003e 'ydb.serverless.yandexcloud.net:2135',\n    'discovery'   =\u003e false,\n    'iam_config'  =\u003e [\n        'temp_dir'       =\u003e './tmp', // Temp directory\n        'root_cert_file' =\u003e './CA.pem', // Root CA file (dedicated server only!)\n\n        // Service account JSON file authentication\n        'service_file'   =\u003e './sa_name.json',\n    ],\n];\n\n$ydb = new Ydb($config);\n```\n\nor:\n```php\n\u003c?php\n\nuse YdbPlatform\\Ydb\\Ydb;\nuse YdbPlatform\\Ydb\\Auth\\Implement\\JwtWithJsonAuthentication;\n\n$config = [\n    'database'    =\u003e '/ru-central1/b1glxxxxxxxxxxxxxxxx/etn0xxxxxxxxxxxxxxxx',\n    'endpoint'    =\u003e 'ydb.serverless.yandexcloud.net:2135',\n    'discovery'   =\u003e false,\n    'iam_config'  =\u003e [\n        'temp_dir'       =\u003e './tmp', // Temp directory\n        'root_cert_file' =\u003e './CA.pem', // Root CA file (dedicated server only!)\n    ],\n            \n    'credentials' =\u003e new JwtWithJsonAuthentication('./jwtjson.json')\n];\n\n$ydb = new Ydb($config);\n```\n## Metadata URL\n\nWhen you deploy a project to VM or function at Yandex.Cloud, you are able to connect to the database using [Metadata URL](https://cloud.yandex.com/docs/compute/operations/vm-connect/auth-inside-vm). Before you start, you should link your service account to an existing or new VM or function.\n\n```php\n\u003c?php\n\nuse YdbPlatform\\Ydb\\Ydb;\n\n$config = [\n\n    // Database path\n    'database'    =\u003e '/ru-central1/b1glxxxxxxxxxxxxxxxx/etn0xxxxxxxxxxxxxxxx',\n\n    // Database endpoint\n    'endpoint'    =\u003e 'ydb.serverless.yandexcloud.net:2135',\n\n    // Auto discovery (dedicated server only)\n    'discovery'   =\u003e false,\n\n    // IAM config\n    'iam_config'  =\u003e [\n        'temp_dir'     =\u003e './tmp', // Temp directory\n        'use_metadata' =\u003e true,\n    ],\n];\n\n$ydb = new Ydb($config);\n```\nor\n```php\n\u003c?php\n\nuse YdbPlatform\\Ydb\\Ydb;\nuse YdbPlatform\\Ydb\\Auth\\Implement\\MetadataAuthentication;\n\n$config = [\n\n    // Database path\n    'database'    =\u003e '/ru-central1/b1glxxxxxxxxxxxxxxxx/etn0xxxxxxxxxxxxxxxx',\n\n    // Database endpoint\n    'endpoint'    =\u003e 'ydb.serverless.yandexcloud.net:2135',\n\n    // Auto discovery (dedicated server only)\n    'discovery'   =\u003e false,\n\n    // IAM config\n    'iam_config'  =\u003e [\n        'temp_dir'     =\u003e './tmp', // Temp directory\n    ],\n    'credentials' =\u003e new MetadataAuthentication()\n];\n\n$ydb = new Ydb($config);\n```\n\n## Anonymous\n\n```php\n\u003c?php\n\nuse YdbPlatform\\Ydb\\Ydb;\n\n$config = [\n\n    // Database path\n    'database'    =\u003e '/local',\n\n    // Database endpoint\n    'endpoint'    =\u003e 'localhost:2136',\n\n    // Auto discovery (dedicated server only)\n    'discovery'   =\u003e false,\n\n    // IAM config\n    'iam_config'  =\u003e [\n        'anonymous' =\u003e true,\n        'insecure' =\u003e true,\n    ],\n];\n\n$ydb = new Ydb($config);\n```\n\nor:\n```php\n\u003c?php\n\nuse YdbPlatform\\Ydb\\Ydb;\nuse YdbPlatform\\Ydb\\Auth\\Implement\\AnonymousAuthentication;\n\n$config = [\n\n    // Database path\n    'database'    =\u003e '/local',\n\n    // Database endpoint\n    'endpoint'    =\u003e 'localhost:2136',\n\n    // Auto discovery (dedicated server only)\n    'discovery'   =\u003e false,\n\n    // IAM config\n    'iam_config'  =\u003e [\n        'insecure' =\u003e true,\n    ],\n    \n    'credentials' =\u003e new AnonymousAuthentication()\n];\n\n$ydb = new Ydb($config);\n```\n\n## Determined by environment variables\n\n```php\n\u003c?php\n\nuse YdbPlatform\\Ydb\\Ydb;\nuse YdbPlatform\\Ydb\\Auth\\Implement\\EnvironCredentials;\n\n$config = [\n\n    // Database path\n    'database'    =\u003e '/local',\n\n    // Database endpoint\n    'endpoint'    =\u003e 'localhost:2136',\n\n    // Auto discovery (dedicated server only)\n    'discovery'   =\u003e false,\n\n    // IAM config\n    'iam_config'  =\u003e [\n        'insecure' =\u003e true,\n    ],\n    \n    'credentials' =\u003e new EnvironCredentials()\n];\n\n$ydb = new Ydb($config);\n```\n\nThe following algorithm that is the same for YDB-PHP-SDK applies:\n\n1. If the value of the `YDB_SERVICE_ACCOUNT_KEY_FILE_CREDENTIALS` environment variable is set, the **System Account Key** authentication mode is used and the key is taken from the file whose name is specified in this variable.\n2. Otherwise, if the value of the `YDB_ANONYMOUS_CREDENTIALS` environment variable is set to 1, the anonymous authentication mode is used.\n3. Otherwise, if the value of the `YDB_METADATA_CREDENTIALS` environment variable is set to 1, the **Metadata** authentication mode is used.\n4. Otherwise, if the value of the `YDB_ACCESS_TOKEN_CREDENTIALS` environment variable is set, the **Access token** authentication mode is used, where the this variable value is passed.\n5. Otherwise, the **Metadata** authentication mode is used.\n\n## Static credentials\n\n```php\n\u003c?php\n\nuse YdbPlatform\\Ydb\\Ydb;\nuse YdbPlatform\\Ydb\\Auth\\Implement\\StaticAuthentication;\n\n$config = [\n\n    // Database path\n    'database'    =\u003e '/local',\n\n    // Database endpoint\n    'endpoint'    =\u003e 'localhost:2136',\n\n    // Auto discovery (dedicated server only)\n    'discovery'   =\u003e false,\n\n    // IAM config\n    'iam_config'  =\u003e [\n        'insecure' =\u003e true,\n    ],\n    \n    'credentials' =\u003e new StaticAuthentication($user, $password)\n];\n\n$ydb = new Ydb($config);\n```\n\n## Reading from text file\n\n```php\n\u003c?php\n\nuse YdbPlatform\\Ydb\\Ydb;\nuse YdbPlatform\\Ydb\\Auth\\ReadTokenFromFile;\n\n$config = [\n\n    // Database path\n    'database'    =\u003e '/local',\n\n    // Database endpoint\n    'endpoint'    =\u003e 'localhost:2136',\n\n    // Auto discovery (dedicated server only)\n    'discovery'   =\u003e false,\n\n    // IAM config\n    'iam_config'  =\u003e [\n        'insecure' =\u003e true,\n    ],\n    \n    'credentials' =\u003e new ReadTokenFromFile($tokenPath, $refreshTime)\n];\n\n$ydb = new Ydb($config);\n```\n\n# Usage\n\nYou should initialize a session from the Table service to start querying with retry.\n\n```php\n\u003c?php\n\nuse YdbPlatform\\Ydb\\Ydb;\n\n$config = [\n    // ...\n];\n\n$ydb = new Ydb($config);\n\n// obtaining the Table service\n$table = $ydb-\u003etable();\n\n$result = $table-\u003eretryTransaction(function(Session $session){\n    // making a query\n    return $session-\u003equery('select * from `users` limit 10;');\n}, true);\n\n$users_count = $result-\u003erowCount();\n$users = $result-\u003erows();\n\n$columns = $result-\u003ecolumns();\n\n```\n\nAs soon as your script is finished, the session will be destroyed.\n\n## Customizing queries\n\nNormally, a regular query through the `query()` method is sufficient, but in exceptional cases, you may need to fine-tune the query settings. You could do it using the query builder:\n\n```php\n\u003c?php\n\n$result = $table-\u003eretryTransaction(function(Session $session){\n\n    // creating a new query builder instance\n    $query = $session-\u003enewQuery('select * from `users` limit 10;');\n    \n    // a setting to keep in cache\n    $query-\u003ekeepInCache();\n    \n    // a setting to begin a transaction with the given mode\n    $query-\u003ebeginTx('stale');\n    \n    return $query-\u003eexecute();\n}, true);\n```\n\nMethods of the query builder:\n\n- `keepInCache(bool $value)` - keep in cache (default: `true`)\n- `collectStats(int $value)` - collect stats (default: 1)\n- `parameters(array $parameters)` - parameters\n- `operationParams(\\Ydb\\Operations\\OperationParams $operation_params)` - operation params\n- `beginTx(string $mode)` - begin a transaction with the given [mode](https://ydb.tech/en/docs/concepts/transactions):\n    - stale\n    - online\n    - online_inconsistent\n    - serializable\n    - snapshot\n- `txControl(\\Ydb\\Table\\TransactionControl $tx_control)` - transaction control with custom settings\n\nYou can chain these methods for convenience.\n\n## Logging\n\nFor logging purposes, you need use class, which implements `\\Psr\\Log\\LoggerInterface`.\nYDB-PHP-SDK has build-in loggers in `YdbPlatform\\Ydb\\Logger` namespace:\n* `NullLogger` - default\n* `SimpleStdLogger($level)` - logger, which push logs in STDERR. \n\nExample of using:\n```php\n$config = [\n    'logger' =\u003e new \\YdbPlatform\\Ydb\\Logger\\SimpleStdLogger(\\YdbPlatform\\Ydb\\Logger\\SimpleStdLogger::INFO)\n]\n$ydb = new \\YdbPlatform\\Ydb\\Ydb($config);\n```\n\n## gRPC\n\n### gRPC client's options\nYou can customize the gRPC client's behavior by setting options in config array\n\nExample of using:\n```php\n$config = [\n    // ...\n    'grpc' =\u003e [\n        'opts' =\u003e [\n            'grpc.max_receive_message_length' =\u003e 8*1024*1024,\n            'grpc.default_compression_algorithm' =\u003e 2,\n            'grpc.default_compression_level' =\u003e 2,\n        ],\n    ],\n];\n$ydb = new \\YdbPlatform\\Ydb\\Ydb($config);\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fydb-platform%2Fydb-php-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fydb-platform%2Fydb-php-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fydb-platform%2Fydb-php-sdk/lists"}