Skip to content

Commit

Permalink
Update docs and config files - 1. (#57)
Browse files Browse the repository at this point in the history
  • Loading branch information
terabytesoftw committed May 3, 2023
1 parent 789d6d0 commit d5f3e87
Show file tree
Hide file tree
Showing 11 changed files with 336 additions and 63 deletions.
4 changes: 4 additions & 0 deletions .editorconfig
Expand Up @@ -10,6 +10,10 @@ indent_style = space
indent_size = 4
trim_trailing_whitespace = true

[*.php]
ij_php_space_before_short_closure_left_parenthesis = false
ij_php_space_after_type_cast = true

[*.md]
trim_trailing_whitespace = false

Expand Down
20 changes: 11 additions & 9 deletions .gitattributes
Expand Up @@ -22,16 +22,18 @@
*.ttf binary

# Ignore some meta files when creating an archive of this repository
/.github export-ignore
/.editorconfig export-ignore
/.gitattributes export-ignore
/.gitignore export-ignore
/.scrutinizer.yml export-ignore
/phpunit.xml.dist export-ignore
/tests export-ignore
/docs export-ignore
/.github export-ignore
/.editorconfig export-ignore
/.gitattributes export-ignore
/.gitignore export-ignore
/.phpunit-watcher.yml export-ignore
/.styleci.yml export-ignore
/infection.json.dist export-ignore
/phpunit.xml.dist export-ignore
/psalm.xml export-ignore
/tests export-ignore
/docs export-ignore

# Avoid merge conflicts in CHANGELOG
# https://about.gitlab.com/2015/02/10/gitlab-reduced-merge-conflicts-by-90-percent-with-changelog-placeholders/
/CHANGELOG.md merge=union

30 changes: 30 additions & 0 deletions .github/CONTRIBUTING.md
Expand Up @@ -16,6 +16,36 @@ Since Yii 3 consists of many packages, we have a [special development tool](http

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

4. Create a new branch for your changes.

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.

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.

5. [Check your changes](/docs/en/testing.md).

## Reporting issues

Please follow the guidelines below when creating an issue so that your issue can be more promptly resolved:

* Provide information including: the version of PHP, dbms and the type of operating system.
* Provide the **complete** error call stack if available. A screenshot to explain the issue is very welcome.
* Describe the steps for reproducing the issue. It would be even better if you could provide code to reproduce the issue.
* If possible you may even create a failing unit test and [send it as a pull request](#git-workflow).

If the issue is related to one of the dbms packages, please report it to the corresponding repository.

If you are unsure, [report it to the main repository](https://github.com/yiisoft/translator-message-db/issues/new) (<https://github.com/yiisoft/translator-message-db/issues>).

**Do not report an issue if**

* you are asking how to use some **Yii Logging 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.
* your issue is about security. Please [contact us directly](https://www.yiiframework.com/security/) to report security issues.

**Avoid duplicated issues**

Before you report an issue, please search through [existing issues](https://github.com/yiisoft/translator-message-db/issues) to see if your issue is already reported or fixed to make sure you are not reporting a duplicated issue.

If you don't have any particular package in mind to start with:

- [Check roadmap](https://github.com/yiisoft/docs/blob/master/003-roadmap.md).
Expand Down
13 changes: 4 additions & 9 deletions .gitignore
Expand Up @@ -12,24 +12,19 @@ nbproject
# windows thumbnail cache
Thumbs.db

# Mac DS_Store Files
.DS_Store

# composer vendor dir
/vendor

# composer lock file
/composer.lock

# composer itself is not needed
composer.phar

# Mac DS_Store Files
.DS_Store

# phpunit itself is not needed
phpunit.phar
# local phpunit config
/phpunit.xml
# phpunit cache
.phpunit.result.cache

# Phan
analysis.txt

99 changes: 54 additions & 45 deletions README.md
Expand Up @@ -11,13 +11,21 @@ with [`yiisoft/translator`](https://github.com/yiisoft/translator) package.

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

## Supported databases

| Packages | PHP | Versions | CI-Actions |
|:---------------------------------------------------:|:-------------:|:---------------:|:---------------------------------------------------------------------------------------------------------------------------------------------------------:|
| [[db-mssql]](https://github.com/yiisoft/db-mssql) | **8.0 - 8.2** | **2017 - 2022** | [![mssql](https://github.com/yiisoft/translator-message-db/actions/workflows/mssql.yml/badge.svg)](https://github.com/yiisoft/translator-message-db/actions/workflows/mssql.yml) | |
| [[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/translator-message-db/actions/workflows/mysql.yml/badge.svg)](https://github.com/yiisoft/translator-message-db/actions/workflows/mysql.yml) |
| [[db-oracle]](https://github.com/yiisoft/db-oracle) | **8.0 - 8.2** | **11C - 21C** | [![oracle](https://github.com/yiisoft/translator-message-db/actions/workflows/oracle.yml/badge.svg)](https://github.com/yiisoft/translator-message-db/actions/workflows/oracle.yml) |
| [[db-pgsql]](https://github.com/yiisoft/db-pgsql) | **8.0 - 8.2** | **9.0 - 15.0** | [![pgsql](https://github.com/yiisoft/translator-message-db/actions/workflows/pgsql.yml/badge.svg)](https://github.com/yiisoft/translator-message-db/actions/workflows/pgsql.yml) |
| [[db-sqlite]](https://github.com/yiisoft/db-sqlite) | **8.0 - 8.2** | **3:latest** | [![sqlite](https://github.com/yiisoft/translator-message-db/actions/workflows/sqlite.yml/badge.svg)](https://github.com/yiisoft/translator-message-db/actions/workflows/sqlite.yml) |

## Requirements

- PHP 8.0 or higher.
Expand All @@ -35,25 +43,44 @@ composer require yiisoft/translator-message-db --prefer-dist

### Quick start

**Step 1.** You need a configured database connection (for example using [`yiisoft/db-sqlite`](https://github.com/yiisoft/db-sqlite))
and [`yiisoft/yii-db-migration`](https://github.com/yiisoft/yii-db-migration) package.
**Step 1.** You need a configured database connection for create migration and use in `yiisoft/translator-message-db` package,
for more information see [yiisoft/db](https://github.com/yiisoft/db/tree/master/docs/en#create-connection).

**Step 2.** Create migration for `source_message` and `message` tables:

For default tables:

Add to `config/params.php`:
```php
...
'yiisoft/yii-db-migration' => [
'updateNamespace' => ['Yiisoft\\Translator\\Message\\Db\\migrations'],
],
...
DbHelper::ensureTable($db);
```

and run the following command in console for create tables for db storage:
For custom tables:

```shell
./yii migrate/up
```php
DbHelper::ensureTables($db, '{{%custom_source_message_table}}', '{{%custom_message_table}}');
```

For dropping tables:

```php
DbHelper::dropTables($db);
```

**Step 2.** In case you use [`yiisoft/config`](http://github.com/yiisoft/config), you will get configuration automatically. If not, the following DI container configuration is necessary:
For custom tables:

```php
DbHelper::dropTable($db, '{{%custom_source_message_table}}', '{{%custom_message_table}}');
```

> Note: Additionally you can import the `RAW SQL` directly to create the tables.
>
>- [schema-mssql](/docs/en/migration/schema-mssql.sql).
>- [schema-mysql](/docs/en/migration/schema-mysql.sql).
>- [schema-oracle](/docs/en/migration/schema-oci.sql).
>- [schema-pgsql](/docs/en/migration/schema-pgsql.sql).
>- [schema-sqlite](/docs/en/migration/schema-sqlite.sql).
**Step 3.** In case you use [`yiisoft/config`](http://github.com/yiisoft/config), you will get configuration automatically. If not, the following DI container configuration is necessary:

```php
<?php
Expand Down Expand Up @@ -126,39 +153,14 @@ $data = [
$messageSource->write($category, $language, $data);
```

## Testing

### Unit testing

The package is tested with [PHPUnit](https://phpunit.de/). To run tests:

```shell
./vendor/bin/phpunit
```

### Mutation testing

The package tests are checked with [Infection](https://infection.github.io/) mutation framework with
[Infection Static Analysis Plugin](https://github.com/Roave/infection-static-analysis-plugin). To run it:

```shell
./vendor/bin/roave-infection-static-analysis-plugin
```

### Static analysis
## Support

The code is statically analyzed with [Psalm](https://psalm.dev/). To run static analysis:

```shell
./vendor/bin/psalm
```

## License
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.
You may also check out other [Yii Community Resources](https://www.yiiframework.com/community).

The Yii Translator DB Message Storage is free software. It is released under the terms of the BSD License.
Please see [`LICENSE`](./LICENSE.md) for more information.
## Testing

Maintained by [Yii Software](https://www.yiiframework.com/).
[Check the testing instructions](/docs/en/testing.md) to learn about testing.

## Support the project

Expand All @@ -171,3 +173,10 @@ Maintained by [Yii Software](https://www.yiiframework.com/).
[![Telegram](https://img.shields.io/badge/telegram-join-1DA1F2?style=flat&logo=telegram)](https://t.me/yii3en)
[![Facebook](https://img.shields.io/badge/facebook-join-1DA1F2?style=flat&logo=facebook&logoColor=ffffff)](https://www.facebook.com/groups/yiitalk)
[![Slack](https://img.shields.io/badge/slack-join-1DA1F2?style=flat&logo=slack)](https://yiiframework.com/go/slack)

## License

The Yii Translator DB Message Storage is free software. It is released under the terms of the BSD License.
Please see [`LICENSE`](./LICENSE.md) for more information.

Maintained by [Yii Software](https://www.yiiframework.com/).
23 changes: 23 additions & 0 deletions docs/en/migration/schema-mssql.sql
@@ -0,0 +1,23 @@
/**
* Database schema required by yiisoft/translator-message-db for MSSQL.
*/
CREATE TABLE [dbo].[source_message]
(
[id] INT IDENTITY NOT NULL,
[category] NVARCHAR(255),
[message_id] NVARCHAR(max),
[comment] NVARCHAR(max)
);

CREATE UNIQUE CLUSTERED INDEX [PK_source_message] ON [dbo].[source_message] ([id]);
CREATE INDEX [IDX_source_message-category] ON [dbo].[source_message] ([category]);

CREATE TABLE [dbo].[message]
(
[id] INT NOT NULL,
[locale] NVARCHAR(16) NOT NULL,
[translation] NVARCHAR(max)
);

CREATE UNIQUE CLUSTERED INDEX [PK_message-id-locale] ON [dbo].[message] ([id], [locale]);
CREATE INDEX [IDX_message-locale] ON [dbo].[message] ([locale]);
23 changes: 23 additions & 0 deletions docs/en/migration/schema-mysql.sql
@@ -0,0 +1,23 @@
/**
* Database schema required by yiisoft/translator-message-db for MySQL.
*/
CREATE TABLE `source_message`
(
[id] INT AUTO_INCREMENT PRIMARY KEY NOT NULL,
[category] VARCHAR(255) NULL,
[message_id] TEXT NULL,
[comment] TEXT NULL
);

CREATE INDEX `IDX_source_message-id` ON `source_message` (`id`);

CREATE TABLE `message` (
(
`id` INT NOT NULL,
`locale` VARCHAR(16) NOT NULL,
`translation` TEXT NULL,
PRIMARY KEY (`id`, `locale`),
CONSTRAINT `FK_source_message_message` FOREIGN KEY (`id`) REFERENCES `source_message` (`id`) ON DELETE CASCADE
);

CREATE INDEX `IDX_message-locale` ON `message` (`locale`);
42 changes: 42 additions & 0 deletions docs/en/migration/schema-oci.sql
@@ -0,0 +1,42 @@
/**
* Database schema required by yiisoft/translator-message-db for Oracle.
*/
CREATE TABLE "source_message"
(
"id" NUMBER(10) NOT NULL PRIMARY KEY,
"category" VARCHAR2(255),
"message_id" CLOB,
"comment" CLOB
);

CREATE INDEX "IDX_source_message-category" on "source_message" ("category");

CREATE TRIGGER "source_message_TRG"
BEFORE INSERT
ON "source_message"
FOR EACH ROW
BEGIN <<COLUMN_SEQUENCES>> BEGIN
IF INSERTING AND :NEW."id" IS NULL THEN SELECT "source_message_SEQ".NEXTVAL INTO :NEW."id" FROM SYS.DUAL; END IF;
END COLUMN_SEQUENCES;
END;
/

CREATE TABLE "message"
(
"id" NUMBER(10) NOT NULL CONSTRAINT "FK_source_message_message" REFERENCES "source_message" ON DELETE CASCADE,
"locale" VARCHAR2(16) NOT NULL,
"translation" CLOB,
CONSTRAINT "PK_oci_message-id-locale" PRIMARY KEY ("id", "locale")
);

CREATE INDEX "IDX_message-locale" on "message" ("locale");

CREATE TRIGGER "message_TRG"
BEFORE INSERT
ON "message"
FOR EACH ROW
BEGIN <<COLUMN_SEQUENCES>> BEGIN
IF INSERTING AND :NEW."id" IS NULL THEN SELECT "message_SEQ".NEXTVAL INTO :NEW."id" FROM SYS.DUAL; END IF;
END COLUMN_SEQUENCES;
END;
/
22 changes: 22 additions & 0 deletions docs/en/migration/schema-pgsql.sql
@@ -0,0 +1,22 @@
/**
* Database schema required by yiisoft/translator-message-db for PostgreSQL.
*/
CREATE TABLE source_message
(
id SERIAL PRIMARY KEY,
category VARCHAR(255),
message_id TEXT,
comment TEXT
);

CREATE INDEX "IDX_source_message-category" on "source_message" ("category");

CREATE TABLE message
(
id INTEGER NOT NULL CONSTRAINT "FK_source_message_message" REFERENCES "source_message" ON UPDATE RESTRICT ON DELETE CASCADE,
locale VARCHAR(16) NOT NULL,
translation TEXT,
CONSTRAINT "PK_message-id-locale" PRIMARY KEY ("id", "locale")
);

CREATE INDEX "IDX_message-locale" on "message" ("locale");
22 changes: 22 additions & 0 deletions docs/en/migration/schema-sqlite.sql
@@ -0,0 +1,22 @@
/**
* Database schema required by yiisoft/translator-message-db for SQLite.
*/
CREATE TABLE "source_message"
(
id INTEGER NOT NULL CONSTRAINT "PK_source_message" PRIMARY KEY,
category VARCHAR(255),
message_id TEXT,
comment TEXT
);

CREATE INDEX "IDX_source_message-category" on "source_message" ("category");

CREATE TABLE "message"
(
id INTEGER NOT NULL CONSTRAINT "FK_source_message_message" REFERENCES "source_message" ON DELETE CASCADE,
locale VARCHAR(16) NOT NULL,
translation TEXT,
PRIMARY KEY ("id", "locale")
);

CREATE INDEX "IDX_message-locale" on "message" ("locale");

0 comments on commit d5f3e87

Please sign in to comment.