From 57a78d12990af2c41a28522d779d01d2dbe42ebe Mon Sep 17 00:00:00 2001 From: Meritoo Date: Thu, 14 Jun 2018 11:32:54 +0200 Subject: [PATCH] Reorganize documentation & update Readme --- CHANGELOG.md | 1 + README.md | 125 ++------------------------------- docker-compose.yml | 2 +- docs/Base-test-case.md | 50 +++++++++++++ docs/Collection-of-elements.md | 48 +++++++++++++ docs/Development.md | 44 ++++++++++++ docs/Static-methods.md | 21 ++++++ 7 files changed, 172 insertions(+), 119 deletions(-) create mode 100644 docs/Base-test-case.md create mode 100644 docs/Collection-of-elements.md create mode 100644 docs/Development.md create mode 100644 docs/Static-methods.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 9c19981..7cede3e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,3 +4,4 @@ Common and useful classes, methods, exceptions etc. ## 0.0.19 1. Add this changelog +2. Reorganize documentation & update [Readme](README.md) diff --git a/README.md b/README.md index 3be9a87..d74866d 100644 --- a/README.md +++ b/README.md @@ -8,130 +8,19 @@ Common and useful classes, methods, exceptions etc. Run [Composer](https://getcomposer.org) to install this package in your project: ```bash -$ composer require meritoo/common-library +composer require meritoo/common-library ``` > [How to install Composer?](https://getcomposer.org/download) -# Docker +# Usage -Build, create and start Docker's containers by running command: +1. [Base test case (with common methods and data providers)](docs/Base-test-case.md) +2. [Collection of elements](docs/Collection-of-elements.md) +3. [Static methods](docs/Static-methods.md) -```bash -$ docker-compose up -d -``` +# Development -> [What is Docker?](https://www.docker.com/what-docker) - -# Composer - -Install packages by running command: - -```bash -$ docker-compose run composer install -``` - -Update packages by running command: - -```bash -$ docker-compose run composer update -``` - -# Rebuild project and run tests - -```bash -$ docker-compose exec php-cli phing -``` - -> [What is Docker?](https://www.docker.com/what-docker) - -# Static methods - -This package contains a lot of class with static methods, so usage is not so complicated. Just run the static method who would you like to use. Example: - -```php -use Meritoo\Common\Utilities\Arrays; - -$firstElement = Arrays::getFirstElement(['lorem', 'ipsum']); -var_dump($firstElement); // string(5) "lorem" -``` - -# Base test case with common methods and data providers - -Located here: `Meritoo\Common\Test\Base\BaseTestCase`. Just extend the `BaseTestCase` class and use it like in `Meritoo\Common\Test\Utilities\DateTest` class: - -```php -class DateTest extends BaseTestCase -{ - /** - * @param mixed $value Empty value, e.g. "" - * @dataProvider provideEmptyValue - */ - public function testGetDateTimeEmptyValue($value) - { - self::assertFalse(Date::getDateTime($value)); - } - - (...) -} -``` - -or in `Meritoo\Common\Test\Utilities\MimeTypesTest` class: - -```php -class MimeTypesTest extends BaseTestCase -{ - (...) - - /** - * @param bool $mimeType The mime type, e.g. "video/mpeg" - * @dataProvider provideBooleanValue - */ - public function testGetExtensionBooleanMimeType($mimeType) - { - self::assertEquals('', MimeTypes::getExtension($mimeType)); - } - - (...) -} -``` - -# Collection of elements - -Located here: `Meritoo\Common\Collection\Collection`. It's a set of some elements, e.g. objects. It's iterable and countable. Provides very useful methods. Some of them: -- `getFirst()` - returns the first element in the collection -- `getLast()` - returns the last element in the collection -- `isEmpty()` - returns information if collection is empty -- `add($element, $index = null)` - adds given element (at the end of collection) -- `addMultiple($elements, $useIndexes = false)` - adds given elements (at the end of collection) -- `prepend($element)` - prepends given element (adds given element at the beginning of collection) -- `remove($element)` - removes given element - -Examples of usage below. - -### An empty collection - -```php -use Meritoo\Common\Collection\Collection; - -$emptyCollection = new Collection(); -var_dump($emptyCollection->isEmpty()); // bool(true) -``` - -### Simple collection - -```php -use Meritoo\Common\Collection\Collection; - -$elements = [ - 'lorem', - 'ipsum', - 123 => 'dolor', - 345 => 'sit', -]; - -$simpleCollection = new Collection($elements); -var_dump($simpleCollection->has('dolor')); // bool(true) -``` +More information [you can find here](docs/Development.md) Enjoy! diff --git a/docker-compose.yml b/docker-compose.yml index e9a45d8..b62f9e1 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -17,6 +17,6 @@ services: image: ${DOCKER_CONTAINER_OWNER}/${DOCKER_CONTAINER_PROJECT}-php-cli container_name: ${DOCKER_CONTAINER_OWNER}-${DOCKER_CONTAINER_PROJECT}-composer working_dir: /project - command: composer + entrypoint: composer volumes: - .:/project diff --git a/docs/Base-test-case.md b/docs/Base-test-case.md new file mode 100644 index 0000000..529b7f1 --- /dev/null +++ b/docs/Base-test-case.md @@ -0,0 +1,50 @@ +# Meritoo Common Library +Common and useful classes, methods, exceptions etc. + +# Base test case (with common methods and data providers) + +Located here: `Meritoo\Common\Test\Base\BaseTestCase`. Just extend the `BaseTestCase` class and use it like in `Meritoo\Common\Test\Utilities\DateTest` class: + +```php +class DateTest extends BaseTestCase +{ + /** + * @param mixed $value Empty value, e.g. "" + * @dataProvider provideEmptyValue + */ + public function testGetDateTimeEmptyValue($value) + { + self::assertFalse(Date::getDateTime($value)); + } + + (...) +} +``` + +or in `Meritoo\Common\Test\Utilities\MimeTypesTest` class: + +```php +class MimeTypesTest extends BaseTestCase +{ + (...) + + /** + * @param bool $mimeType The mime type, e.g. "video/mpeg" + * @dataProvider provideBooleanValue + */ + public function testGetExtensionBooleanMimeType($mimeType) + { + self::assertEquals('', MimeTypes::getExtension($mimeType)); + } + + (...) +} +``` + +# More + +1. [**Base test case (with common methods and data providers)**](Base-test-case.md) +2. [Collection of elements](Collection-of-elements.md) +3. [Static methods](Static-methods.md) + +[‹ Back to `Readme`](../README.md) diff --git a/docs/Collection-of-elements.md b/docs/Collection-of-elements.md new file mode 100644 index 0000000..79c57fa --- /dev/null +++ b/docs/Collection-of-elements.md @@ -0,0 +1,48 @@ +# Meritoo Common Library +Common and useful classes, methods, exceptions etc. + +# Collection of elements + +Located here: `Meritoo\Common\Collection\Collection`. It's a set of some elements, e.g. objects. It's iterable and countable. Provides very useful methods. Some of them: +- `getFirst()` - returns the first element in the collection +- `getLast()` - returns the last element in the collection +- `isEmpty()` - returns information if collection is empty +- `add($element, $index = null)` - adds given element (at the end of collection) +- `addMultiple($elements, $useIndexes = false)` - adds given elements (at the end of collection) +- `prepend($element)` - prepends given element (adds given element at the beginning of collection) +- `remove($element)` - removes given element + +Examples of usage below. + +### An empty collection + +```php +use Meritoo\Common\Collection\Collection; + +$emptyCollection = new Collection(); +var_dump($emptyCollection->isEmpty()); // bool(true) +``` + +### Simple collection + +```php +use Meritoo\Common\Collection\Collection; + +$elements = [ + 'lorem', + 'ipsum', + 123 => 'dolor', + 345 => 'sit', +]; + +$simpleCollection = new Collection($elements); +var_dump($simpleCollection->has('dolor')); // bool(true) +``` + +# More + +1. [Base test case (with common methods and data providers)](Base-test-case.md) +2. [**Collection of elements**](Collection-of-elements.md) +3. [Static methods](Static-methods.md) + +[‹ Back to `Readme`](../README.md) diff --git a/docs/Development.md b/docs/Development.md new file mode 100644 index 0000000..35fa88c --- /dev/null +++ b/docs/Development.md @@ -0,0 +1,44 @@ +# Meritoo Common Library +Development-related information + +# Getting started + +### Docker + +Build, create and start Docker's containers by running command: + +```bash +docker-compose up -d +``` + +> [What is Docker?](https://www.docker.com/what-docker) + +### Composer + +Install packages by running command: + +```bash +docker-compose run composer install +``` + +Update packages by running command: + +```bash +docker-compose run composer update +``` + +### Tests + +Rebuild project and run tests by running command: + +```bash +docker-compose exec php-cli phing +``` + +Run tests only by running command: + +```bash +docker-compose exec php-cli phpunit +``` + +[‹ Back to `Readme`](../README.md) diff --git a/docs/Static-methods.md b/docs/Static-methods.md new file mode 100644 index 0000000..5711dd6 --- /dev/null +++ b/docs/Static-methods.md @@ -0,0 +1,21 @@ +# Meritoo Common Library +Common and useful classes, methods, exceptions etc. + +# Static methods + +This package contains a lot of class with static methods, so usage is not so complicated. Just run the static method who would you like to use. Example: + +```php +use Meritoo\Common\Utilities\Arrays; + +$firstElement = Arrays::getFirstElement(['lorem', 'ipsum']); +var_dump($firstElement); // string(5) "lorem" +``` + +# More + +1. [Base test case (with common methods and data providers)](Base-test-case.md) +2. [Collection of elements](Collection-of-elements.md) +3. [**Static methods**](Static-methods.md) + +[‹ Back to `Readme`](../README.md)