Skip to content

Commit 22abb9b

Browse files
terabytesoftwterabytesoftw
authored
Update docs and config files - 1. (#60)
1 parent 4ffc6a9 commit 22abb9b

File tree

10 files changed

+222
-36
lines changed

10 files changed

+222
-36
lines changed

‎.editorconfig‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,10 @@ indent_style = space
1010
indent_size = 4
1111
trim_trailing_whitespace = true
1212

13+
[*.php]
14+
ij_php_space_before_short_closure_left_parenthesis = false
15+
ij_php_space_after_type_cast = true
16+
1317
[*.md]
1418
trim_trailing_whitespace = false
1519

‎.github/CONTRIBUTING.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,36 @@ Since Yii 3 consists of many packages, we have a [special development tool](http
1616

1717
3. Now you are ready. Fork any package listed in `packages.php` and do `./yii-dev install username/package`.
1818

19+
4. Create a new branch for your changes.
20+
21+
If you are only going to make a pull request in a single repository, simply create the new branch, where the name correctly identifies the fix or feature to be made.
22+
23+
if you are going to make a pull request in multiple repositories, create a **new branch with the same name in all repositories**, this allows our github actions workflow to sync all branches, and tests to run correctly.
24+
25+
5. [Check your changes](/docs/en/testing.md).
26+
27+
## Reporting issues
28+
29+
Please follow the guidelines below when creating an issue so that your issue can be more promptly resolved:
30+
31+
* Provide information including: the version of PHP, dbms and the type of operating system.
32+
* Provide the **complete** error call stack if available. A screenshot to explain the issue is very welcome.
33+
* Describe the steps for reproducing the issue. It would be even better if you could provide code to reproduce the issue.
34+
* If possible you may even create a failing unit test and [send it as a pull request](#git-workflow).
35+
36+
If the issue is related to one of the dbms packages, please report it to the corresponding repository.
37+
38+
If you are unsure, [report it to the main repository](https://github.com/yiisoft/cache-db/issues/new) (<https://github.com/yiisoft/cache-db/issues>).
39+
40+
**Do not report an issue if**
41+
42+
* you are asking how to use some **Yii Cache Library** feature. You should use [the forum](https://forum.yiiframework.com/c/yii-3-0/63) or [telegram](https://t.me/yii3en) for this purpose.
43+
* your issue is about security. Please [contact us directly](https://www.yiiframework.com/security/) to report security issues.
44+
45+
**Avoid duplicated issues**
46+
47+
Before you report an issue, please search through [existing issues](https://github.com/yiisoft/cache-db/issues) to see if your issue is already reported or fixed to make sure you are not reporting a duplicated issue.
48+
1949
If you don't have any particular package in mind to start with:
2050

2151
- [Check roadmap](https://github.com/yiisoft/docs/blob/master/003-roadmap.md).

‎README.md‎

Lines changed: 42 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -8,23 +8,22 @@
88

99
[![Latest Stable Version](https://poser.pugx.org/yiisoft/cache-db/v/stable.png)](https://packagist.org/packages/yiisoft/cache-db)
1010
[![Total Downloads](https://poser.pugx.org/yiisoft/cache-db/downloads.png)](https://packagist.org/packages/yiisoft/cache-db)
11-
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/yiisoft/cache-db/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/yiisoft/cache-db/?branch=master)
12-
[![Code Coverage](https://scrutinizer-ci.com/g/yiisoft/cache-db/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/yiisoft/cache-db/?branch=master)
11+
[![codecov](https://codecov.io/gh/yiisoft/cache-db/branch/master/graph/badge.svg?token=H7YALMK1YN)](https://codecov.io/gh/yiisoft/cache-db)
1312
[![Mutation testing badge](https://img.shields.io/endpoint?style=flat&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fyiisoft%2Fcache-db%2Fmaster)](https://dashboard.stryker-mutator.io/reports/github.com/yiisoft/cache-db/master)
1413
[![static analysis](https://github.com/yiisoft/cache-db/workflows/static%20analysis/badge.svg)](https://github.com/yiisoft/cache-db/actions?query=workflow%3A%22static+analysis%22)
1514
[![type-coverage](https://shepherd.dev/github/yiisoft/cache-db/coverage.svg)](https://shepherd.dev/github/yiisoft/cache-db)
1615

1716
This package implements database-based [PSR-16](https://www.php-fig.org/psr/psr-16/) cache.
1817

19-
## Support databases:
18+
## Supported databases
2019

2120
| Packages | PHP | Versions | CI-Actions |
2221
|:---------------------------------------------------:|:-------------:|:---------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------:|
23-
| [[db-mssql]](https://github.com/yiisoft/db-mssql) | **8.0 - 8.1** | **2017 - 2019** | [![mssql](https://github.com/yiisoft/cache-db/actions/workflows/mssql.yml/badge.svg)](https://github.com/yiisoft/cache-db/actions/workflows/mssql.yml) | |
24-
| [[db-mysql]](https://github.com/yiisoft/db-mysql) | **8.0 - 8.1** | **5.7 - 8.0** | [![mysql](https://github.com/yiisoft/cache-db/actions/workflows/mysql.yml/badge.svg)](https://github.com/yiisoft/cache-db/actions/workflows/mysql.yml) |
25-
| [[db-oracle]](https://github.com/yiisoft/db-oracle) | **8.0 - 8.1** | **11c - 21c** | [![oracle](https://github.com/yiisoft/cache-db/actions/workflows/oracle.yml/badge.svg)](https://github.com/yiisoft/cache-db/actions/workflows/oracle.yml) |
26-
| [[db-pgsql]](https://github.com/yiisoft/db-pgsql) | **8.0 - 8.1** | **9.0 - 15.0** | [![pgsql](https://github.com/yiisoft/cache-db/actions/workflows/pgsql.yml/badge.svg)](https://github.com/yiisoft/cache-db/actions/workflows/pgsql.yml) |
27-
| [[db-sqlite]](https://github.com/yiisoft/db-sqlite) | **8,0 - 8.1** | **3:latest** | [![sqlite](https://github.com/yiisoft/cache-db/actions/workflows/sqlite.yml/badge.svg)](https://github.com/yiisoft/cache-db/actions/workflows/sqlite.yml) |
22+
| [[db-mssql]](https://github.com/yiisoft/db-mssql) | **8.0 - 8.2** | **2017 - 2022** | [![mssql](https://github.com/yiisoft/cache-db/actions/workflows/mssql.yml/badge.svg)](https://github.com/yiisoft/cache-db/actions/workflows/mssql.yml) | |
23+
| [[db-mysql/mariadb]](https://github.com/yiisoft/db-mysql) | **8.0 - 8.2** | **5.7-8.0**/**10.4-10.10** | [![mysql](https://github.com/yiisoft/cache-db/actions/workflows/mysql.yml/badge.svg)](https://github.com/yiisoft/cache-db/actions/workflows/mysql.yml) |
24+
| [[db-oracle]](https://github.com/yiisoft/db-oracle) | **8.0 - 8.2** | **11C - 21C** | [![oracle](https://github.com/yiisoft/cache-db/actions/workflows/oracle.yml/badge.svg)](https://github.com/yiisoft/cache-db/actions/workflows/oracle.yml) |
25+
| [[db-pgsql]](https://github.com/yiisoft/db-pgsql) | **8.0 - 8.2** | **9.0 - 15.0** | [![pgsql](https://github.com/yiisoft/cache-db/actions/workflows/pgsql.yml/badge.svg)](https://github.com/yiisoft/cache-db/actions/workflows/pgsql.yml) |
26+
| [[db-sqlite]](https://github.com/yiisoft/db-sqlite) | **8.0 - 8.2** | **3:latest** | [![sqlite](https://github.com/yiisoft/cache-db/actions/workflows/sqlite.yml/badge.svg)](https://github.com/yiisoft/cache-db/actions/workflows/sqlite.yml) |
2827

2928
## Requirements
3029

@@ -39,9 +38,38 @@ The package could be installed with composer:
3938
composer require yiisoft/cache-db --prefer-dist
4039
```
4140

41+
## Database Preparing
42+
43+
Package provides two way for preparing database:
44+
45+
1. Raw SQL. You can use it with the migration package used in your application.
46+
47+
- [MSSQL](/docs/en/migration/schema-mssql.sql),
48+
- [MySQL / MariaDB](/docs/en/migration/schema-mysql.sql),
49+
- [Oracle](/docs/en/migration/schema-oci.sql),
50+
- [PostgreSQL](/docs/en/migration/schema-pgsql.sql),
51+
- [SQLite](/docs/en/migration/schema-sqlite.sql),
52+
53+
2. `DbHelper` for create/drop cache table (by default `{{%cache}}`).
54+
55+
```php
56+
// Create table with default name
57+
DbHelper::ensureTable($db);
58+
59+
// Create table with custom name
60+
DbHelper::ensureTable($db, '{{%custom_cache_table}}');
61+
62+
// Drop table with default name
63+
DbHelper::dropTable($db);
64+
65+
// Drop table with custom name
66+
DbHelper::dropTable($db, '{{%custom_cache_table}}');
67+
```
68+
4269
## Configuration
4370

44-
When creating an instance of `\Yiisoft\Cache\Db\DbCache`, you must pass an instance of the database connection:
71+
When creating an instance of `\Yiisoft\Cache\Db\DbCache`, you must pass an instance of the database connection,
72+
for more information see [yiisoft/db](https://github.com/yiisoft/db/tree/master/docs/en#create-connection).
4573

4674
```php
4775
$cache = new \Yiisoft\Cache\Db\DbCache($db, $table, $gcProbability);
@@ -104,32 +132,14 @@ $cache->setLogger(new \Yiisoft\Log\Logger());
104132

105133
This allows you to log cache operations, when ocurring errors, etc.
106134

107-
## Testing
108-
109-
### Unit testing
110-
111-
The package is tested with [PHPUnit](https://phpunit.de/). To run tests:
112-
113-
```shell
114-
./vendor/bin/phpunit
115-
```
116-
117-
### Mutation testing
135+
## Support
118136

119-
The package tests are checked with [Infection](https://infection.github.io/) mutation framework with
120-
[Infection Static Analysis Plugin](https://github.com/Roave/infection-static-analysis-plugin). To run it:
137+
If you need help or have a question, the [Yii Forum](https://forum.yiiframework.com/c/yii-3-0/db/68) is a good place for that.
138+
You may also check out other [Yii Community Resources](https://www.yiiframework.com/community).
121139

122-
```shell
123-
./vendor/bin/roave-infection-static-analysis-plugin
124-
```
125-
126-
### Static analysis
127-
128-
The code is statically analyzed with [Psalm](https://psalm.dev/). To run static analysis:
140+
## Testing
129141

130-
```shell
131-
./vendor/bin/psalm
132-
```
142+
[Check the testing instructions](/docs/en/testing.md) to learn about testing.
133143

134144
### Support the project
135145

‎UPGRADE.md‎

Lines changed: 0 additions & 4 deletions
This file was deleted.

‎docs/en/migration/schema-mssql.sql‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
/**
2+
* Database schema required by yiisoft/cache db for MSSQL.
3+
*/
4+
CREATE TABLE [dbo].[cache] (
5+
[id] NVARCHAR(128) NOT NULL,
6+
[data] VARBINARY(MAX) NULL,
7+
[expire] INT NULL,
8+
CONSTRAINT [PK_cache] PRIMARY KEY ([id])
9+
);

‎docs/en/migration/schema-mysql.sql‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
/**
2+
* Database schema required by yiisoft/cache db for MySQL.
3+
*/
4+
CREATE TABLE `cache` (
5+
`id` VARCHAR(128) NOT NULL,
6+
`data` BLOB,
7+
`expire` INT,
8+
PRIMARY KEY (`id`)
9+
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

‎docs/en/migration/schema-oci.sql‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
/**
2+
* Database schema required by yiisoft/cache db for Oracle.
3+
*/
4+
CREATE TABLE "cache" (
5+
"id" VARCHAR2(128) NOT NULL,
6+
"data" BLOB,
7+
"expire" INTEGER,
8+
CONSTRAINT "PK_cache" PRIMARY KEY ("id") ENABLE
9+
);

‎docs/en/migration/schema-pgsql.sql‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
/**
2+
* Database schema required by yiisoft/cache db for PostgreSQL.
3+
*/
4+
CREATE TABLE "cache" (
5+
id VARCHAR(128) NOT NULL,
6+
data BYTEA,
7+
expire INTEGER,
8+
PRIMARY KEY (id)
9+
);

‎docs/en/migration/schema-sqlite.sql‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
/**
2+
* Database schema required by yiisoft/cache db for SQLite.
3+
*/
4+
CREATE TABLE "cache" (
5+
id VARCHAR(128) NOT NULL,
6+
data BLOB,
7+
expire INTEGER,
8+
PRIMARY KEY (id)
9+
);

‎docs/en/testing.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Testing
2+
3+
This package can be tested globally or individually for each DBMS.
4+
5+
- [MSSQL](https://github.com/yiisoft/db-mssql)
6+
- [MySQL/MariaDB](https://github.com/yiisoft/db-mysql)
7+
- [Oracle](https://github.com/yiisoft/db-oracle)
8+
- [PostgreSQL](https://github.com/yiisoft/db-pgsql)
9+
- [SQLite](https://github.com/yiisoft/db-sqlite)
10+
11+
## Github actions
12+
13+
All our packages have github actions by default, so you can test your [contribution](https://github.com/yiisoft/cache-db/blob/master/.github/CONTRIBUTING.md) in the cloud.
14+
15+
> Note: We recommend pull requesting in draft mode until all tests pass.
16+
17+
## Docker images
18+
19+
For greater ease it is recommended to use Docker containers for each DBMS, for this you can use the [docker-compose.yml](https://docs.docker.com/compose/compose-file/) file that in the root directory of each package.
20+
21+
- [MSSQL 2022](https://github.com/yiisoft/db-mssql/blob/master/docker-compose.yml)
22+
- [MySQL 8](https://github.com/yiisoft/db-mysql/blob/master/docker-compose.yml)
23+
- [MariaDB 10.11](https://github.com/yiisoft/db-mysql/blob/master/docker-compose-mariadb.yml)
24+
- [Oracle 21](https://github.com/yiisoft/db-oracle/blob/master/docker-compose.yml)
25+
- [PostgreSQL 15](https://github.com/yiisoft/db-pgsql/blob/master/docker-compose.yml)
26+
27+
For running the Docker containers you can use the following command:
28+
29+
```shell
30+
docker compose up -d
31+
```
32+
33+
## Unit testing
34+
35+
The package is tested with [PHPUnit](https://phpunit.de/).
36+
37+
### Global testing
38+
39+
The following steps are required to run the tests.
40+
41+
1. Run all Docker containers for each dbms.
42+
2. Install the dependencies of the project with composer.
43+
3. Run the tests.
44+
45+
```shell
46+
vendor/bin/phpunit
47+
```
48+
49+
### Individual testing
50+
51+
The following steps are required to run the tests.
52+
53+
1. Run the Docker container for the dbms you want to test.
54+
2. Install the dependencies of the project with composer.
55+
3. Run the tests.
56+
57+
```shell
58+
vendor/bin/phpunit --testsuite=Pgsql
59+
```
60+
61+
Suites available:
62+
- Mssql
63+
- Mysql
64+
- Oracle
65+
- Pgsql
66+
- Sqlite
67+
68+
## Composer require checker
69+
70+
This package uses [composer-require-checker](https://github.com/maglnet/ComposerRequireChecker) to check if all dependencies are correctly defined in `composer.json`.
71+
72+
To run the checker, execute the following command:
73+
74+
```shell
75+
./vendor/bin/composer-require-checker
76+
```
77+
78+
## Mutation testing
79+
80+
The package tests are checked with [Infection](https://infection.github.io/) mutation framework with
81+
[Infection Static Analysis Plugin](https://github.com/Roave/infection-static-analysis-plugin). To run it:
82+
83+
```shell
84+
./vendor/bin/roave-infection-static-analysis-plugin
85+
```
86+
87+
## Static analysis
88+
89+
The code is statically analyzed with [Psalm](https://psalm.dev/). To run static analysis:
90+
91+
```shell
92+
./vendor/bin/psalm
93+
```
94+
95+
## Rector
96+
97+
Use [Rector](https://github.com/rectorphp/rector) to make codebase follow some specific rules or use either newest or any specific version of PHP:
98+
99+
```shell
100+
./vendor/bin/rector
101+
```

0 commit comments

Comments
 (0)