{"id":15026720,"url":"https://github.com/rancoud/database","last_synced_at":"2025-04-09T20:21:41.593Z","repository":{"id":37579861,"uuid":"102277920","full_name":"rancoud/Database","owner":"rancoud","description":"Database Package","archived":false,"fork":false,"pushed_at":"2025-04-01T12:19:56.000Z","size":482,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-01T13:27:46.848Z","etag":null,"topics":["composer","coverage","database","mysql","packagist","pdo","php","php74","php8","php80","php81","phpunit","phpunit9","postgresql","sql","sqlite"],"latest_commit_sha":null,"homepage":"https://packagist.org/packages/rancoud/database","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/rancoud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-03T16:26:36.000Z","updated_at":"2025-04-01T12:19:59.000Z","dependencies_parsed_at":"2024-01-04T11:32:12.254Z","dependency_job_id":"df8ffc30-5a3c-43fe-bfeb-492b2867baa5","html_url":"https://github.com/rancoud/Database","commit_stats":{"total_commits":149,"total_committers":4,"mean_commits":37.25,"dds":0.4563758389261745,"last_synced_commit":"699c0f003c34a858ff10c29985f6a603d62918c6"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rancoud%2FDatabase","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rancoud%2FDatabase/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rancoud%2FDatabase/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rancoud%2FDatabase/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rancoud","download_url":"https://codeload.github.com/rancoud/Database/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248104450,"owners_count":21048340,"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":["composer","coverage","database","mysql","packagist","pdo","php","php74","php8","php80","php81","phpunit","phpunit9","postgresql","sql","sqlite"],"created_at":"2024-09-24T20:04:57.176Z","updated_at":"2025-04-09T20:21:41.572Z","avatar_url":"https://github.com/rancoud.png","language":"PHP","readme":"# Database Package\n\n![Packagist PHP Version Support](https://img.shields.io/packagist/php-v/rancoud/database)\n[![Packagist Version](https://img.shields.io/packagist/v/rancoud/database)](https://packagist.org/packages/rancoud/database)\n[![Packagist Downloads](https://img.shields.io/packagist/dt/rancoud/database)](https://packagist.org/packages/rancoud/database)\n[![Composer dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://github.com/rancoud/database/blob/master/composer.json)\n[![Test workflow](https://img.shields.io/github/actions/workflow/status/rancoud/database/test.yml?branch=master)](https://github.com/rancoud/database/actions/workflows/test.yml)\n[![Codecov](https://img.shields.io/codecov/c/github/rancoud/database?logo=codecov)](https://codecov.io/gh/rancoud/database)\n\nRequest Database (use PDO). Supported drivers: MySQL, PostgreSQL, SQLite.\n\n## Installation\n```php\ncomposer require rancoud/database\n```\n\n## How to use it?\n### Connection to a database\n```php\nuse Rancoud\\Database\\Configurator;\nuse Rancoud\\Database\\Database;\n\n// Create a configurator\n$params = [\n    'driver'    =\u003e 'mysql',\n    'host'      =\u003e 'localhost',\n    'user'      =\u003e 'root',\n    'password'  =\u003e '',\n    'database'  =\u003e 'test_database'\n];\n$databaseConf = new Configurator($params);\n\n// No singleton\n$database = new Database($databaseConf);\n\n// With named instances\n$database = Database::setInstance($databaseConf, 'primary');\n```\n\n## Examples\nFor example we have a table `users` with this schema:\n\n| Field    | Type         | Options                     |\n|----------|--------------|-----------------------------|\n| id       | int(8)       | primary key, auto increment |\n| username | varchar(255) |                             |\n| ranking  | int(8)       |                             |\n\nIn the table we have these data:\n\n| id | username | ranking |\n|----|----------|---------|\n| 1  | taylor   | 10      |\n| 2  | alison   | 30      |\n| 3  | swifts   | 20      |\n\n### Select methods\nThe output is always an array.\n\n#### SelectAll\nReturn all rows\n```php\n$results = $database-\u003eselectAll(\"SELECT * FROM users\");\n\n// Output be like\n[\n    ['id' =\u003e '1', 'username' =\u003e 'taylor', 'ranking' =\u003e 10],\n    ['id' =\u003e '2', 'username' =\u003e 'alison', 'ranking' =\u003e 30],\n    ['id' =\u003e '3', 'username' =\u003e 'swifts', 'ranking' =\u003e 20]\n]\n```\n\n#### SelectRow\nReturn only the first row\n```php\n$results = $database-\u003eselectRow(\"SELECT * FROM users\");\n\n// Output be like\n['id' =\u003e '1', 'username' =\u003e 'taylor', 'ranking' =\u003e 10]\n```\n\n#### SelectCol\nReturn only the first column\n```php\n$results = $database-\u003eselectCol(\"SELECT username FROM users\");\n\n// Output be like\n[\n    'taylor',\n    'alison',\n    'swifts'\n]\n```\n\n#### SelectVar\nReturn only the first value of first line\n```php\n$results = $database-\u003eselectVar(\"SELECT username FROM users WHERE id = 3\");\n\n// Output be like\n'swifts'\n```\n\n#### Select + (Read OR ReadAll)\nHaving the statement and use read to get row by row or readAll for all data.\nUseful when you want to use a specific fetch mode.\n```php\n$statement = $database-\u003eselect(\"SELECT * FROM users\");\n$row = $database-\u003eread($statement);\n\n// Output be like\n['id' =\u003e '1', 'username' =\u003e 'taylor', 'ranking' =\u003e 10]\n\n$statement = $database-\u003eselect(\"SELECT * FROM users\");\n$rows = $database-\u003ereadAll($statement);\n\n// Output be like\n[\n    ['id' =\u003e '1', 'username' =\u003e 'taylor', 'ranking' =\u003e 10],\n    ['id' =\u003e '2', 'username' =\u003e 'alison', 'ranking' =\u003e 30],\n    ['id' =\u003e '3', 'username' =\u003e 'swifts', 'ranking' =\u003e 20]\n]\n```\n\n#### Count\nReturn only the value when using `SELECT COUNT(*) FROM ...`.\n```php\n$count = $database-\u003ecount(\"SELECT COUNT(*) FROM users\");\n\n// Output be like\n3\n```\n\n## Insert\n```php\n// insert with parameters and get last insert id\n$params = ['username' =\u003e 'adam', 'ranking' =\u003e 100];\n$lastInsertId = $database-\u003einsert(\"INSERT INTO users (username, ranking) VALUES (:username, :ranking)\", $params, true);\n\n// Output be like\n4\n```\n\n## Update\n```php\n// update with parameters and get the number of affected rows\n$params = ['username' =\u003e 'adam', 'id' =\u003e 4];\n$affectedRowsCount = $database-\u003eupdate(\"UPDATE users SET username = :username WHERE id = :id\", $params, true);\n\n// Output be like\n1\n```\n\n## Delete\n```php\n// delete with parameters and get the number of affected rows\n$params = ['id' =\u003e 4];\n$affectedRowsCount = $database-\u003edelete(\"DELETE FROM users WHERE id = :id\", $params, true);\n\n// Output be like\n1\n```\n\n## Transactions\nNested transactions are supported for MySQL, PostgreSQL, SQLite.\n```php\n$database-\u003estartTransaction();\n\nif (isOk()) {\n    $database-\u003ecommitTransaction();\n} else {\n    $database-\u003erollbackTransaction();\n}\n```\n\n## Named instances\nYou have to name your instances.  \nThen you can get them by their name.\n```php\nDatabase::setInstance($databaseConfA, 'primary');\nDatabase::setInstance($databaseConfB, 'secondary');\n\n/** A few moments later **/\n\n$db = Database::getInstance('secondary');\n```\n\n## Configurator\n### Constructor Settings\nHere is the description of the array passed to the construct\n\n#### Mandatory keys\n| Parameter | Type   | Description                                                                    |\n|-----------|--------|--------------------------------------------------------------------------------|\n| driver    | string | driver of the database, it will be check with PDO::getAvailableDrivers         |\n| host      | string | hostname of the database (port number may be included, e.g `example.org:5342`) |\n| user      | string | user used to connect to the database                                           |\n| password  | string | password used to connect to the database                                       |\n| database  | string | name of the database                                                           |\n\n#### Optional keys\n| Parameter             | Type   | Default value                                                    | Description                                                                     |\n|-----------------------|--------|------------------------------------------------------------------|---------------------------------------------------------------------------------|\n| save_queries          | bool   | true                                                             | all queries will be saved in memory with execution time and the connection time |\n| persistent_connection | bool   | false                                                            | use persistent connection                                                       |\n| charset               | string | it depends on the driver (MySQL: `utf8mb4` , PostgreSQL: `UTF8`) | set specific database charset                                                   |\n| parameters            | array  | []                                                               | extra parameters used by PDO on connection                                      |\n\n### Methods\n* createPDOConnection(): PDO\n* disablePersistentConnection(): void\n* disableSaveQueries(): void\n* enablePersistentConnection(): void\n* enableSaveQueries(): void\n* getCharset(): string\n* getDatabase(): string\n* getDSN(): string\n* getDriver(): string\n* getHost(): string\n* getParameters(): array\n* getParametersForPDO(): array\n* getPassword(): string\n* getUser(): string\n* hasPersistentConnection(): bool\n* hasSavedQueries(): bool\n* setCharset(charset: string): void\n* setDatabase(database: string): void\n* setDriver(driver: string): void\n* setHost(host: string): void\n* setParameter(key: mixed, value: mixed): void\n* setParameters(parameters: array): void\n* setPassword(password: string): void\n* setUser(user: string): void\n\n## Database\n### Constructor\n#### Mandatory\n| Parameter    | Type         | Description            |\n|--------------|--------------|------------------------|\n| configurator | Configurator | Database configuration |\n\n### General Commands\n* selectAll(sql: string, [parameters: array = []]): array\n* selectRow(sql: string, [parameters: array = []]): array\n* selectCol(sql: string, [parameters: array = []]): array\n* selectVar(sql: string, [parameters: array = []]): mixed\n* insert(sql: string, [parameters: array = []], [getLastInsertId: bool = false]): ?int\n* update(sql: string, [parameters: array = []], [getAffectedRowsCount: bool = false]): ?int\n* delete(sql: string, [parameters: array = []], [getAffectedRowsCount: bool = false]): ?int\n* count(sql: string, [parameters: array = []]): ?int\n* exec(sql: string, [parameters: array = []]): void\n* select(sql: string, [parameters: array = []]): PDOStatement\n* read(statement: PDOStatement, [fetchType: int = PDO::FETCH_ASSOC]): mixed\n* readAll(statement: PDOStatement, [fetchType: int = PDO::FETCH_ASSOC]): array\n\n### Transactions\n* startTransaction(): void\n* completeTransaction(): void\n* commitTransaction(): void\n* rollbackTransaction(): void\n\n### Errors\n* hasErrors(): bool\n* getErrors(): array\n* getLastError(): ?array\n* cleanErrors(): void\n\n### Save Queries\n* hasSavedQueries(): bool\n* enableSaveQueries(): void\n* disableSaveQueries(): void\n* cleanSavedQueries(): void\n* getSavedQueries(): array\n\n### Specific Commands\n* truncateTables(...tables: string): void\n* dropTables(...tables: string): void\n* useSqlFile(filepath: string): void\n\n### Low Level\n* connect(): void\n* disconnect(): void\n* getPDO(): ?PDO\n\n### Static Method\n* setInstance(configurator: Configurator, [name: string = primary]]): self\n* hasInstance([name: string = primary]): bool\n* getInstance([name: string = primary]): ?self\n\n## How to Dev\n`docker compose build \u0026\u0026 docker compose run lib composer ci` for launching tests\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Francoud%2Fdatabase","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Francoud%2Fdatabase","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Francoud%2Fdatabase/lists"}