Merge branch 'develop' to release version 0.1.0

.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,42 @@
+# Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+-   Using welcoming and inclusive language
+-   Being respectful of differing viewpoints and experiences
+-   Gracefully accepting constructive criticism
+-   Focusing on what is best for the community
+-   Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+-   The use of sexualized language or imagery and unwelcome sexual attention or advances
+-   Trolling, insulting/derogatory comments, and personal or political attacks
+-   Public or private harassment
+-   Publishing others’ private information, such as a physical or electronic address, without explicit permission
+-   Other conduct which could reasonably be considered inappropriate in a professional setting
+
+# Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+# Scope
+
+This Code of Conduct applies within all project spaces, and it also applies when an individual is representing the project or its community in public spaces. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+
+# Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [email protected]. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project’s leadership.
+
+# Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at <https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>
+
+For answers to common questions about this code of conduct, see <https://www.contributor-covenant.org/faq>

.github/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contribution Guidelines
+
+## Code of Conduct
+
+For a better community, please read and follow the [code of conduct](./CODE_OF_CONDUCT.md).
+
+## Issues
+
+It is great to include examples in your issues, like what fails or what you want to achieve.
+
+## Branching Model
+
+There are two branches available, `master` and `develop`. All stable changes will go into the `master`, and all unstables to `develop`.
+
+As a result, you always have to make changes on `develop`, and merge back to the same branch, in the case of any PRs. Any requests to merge into `master` directly is likely to be rejected.
+
+## Warming Up
+
+For the development process, install dependencies first:
+
+```bash
+composer install
+```
+
+## Tests, Tests and Tests
+
+Make unit-tests for the new code. Make sure all current tests pass by invoking PHPUnit:
+
+```bash
+./vendor/bin/phpunit
+```
+
+## Documentation
+
+We will be thankful if you update the related documentations along with any changes.
+
+## Static Analysis
+
+We use [Phan](https://github.com/phan/phan) static analyser.
+
+Newly-added code must have no errors reported by Phan. You may suppress an error, if you think it's not applicable. Globally suppressing errors is not a good idea, so make sure you make the suppression as limited and small as possible.
+
+To run Phan, do:
+
+## Coding Guidelines
+
+You should use the [PSR-2](https://www.php-fig.org/psr/psr-2/) and [PSR-12](https://www.php-fig.org/psr/psr-12/) style guides in your code.
+
+## Versioning
+
+This project follows the [semantic versioning](https://semver.org/) guidelines.

.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: Continuous Integration
+
+on:
+    push:
+        branches: [master, develop]
+    pull_request:
+        branches: [develop]
+
+jobs:
+    run-tests:
+        name: Run PHPUnit Tests
+        runs-on: ${{ matrix.os }}
+        strategy:
+            matrix:
+                os: [ubuntu-latest, macos-latest, windows-latest]
+        steps:
+            - uses: actions/checkout@v2
+
+            - name: Prepare PHP 7.4
+              uses: shivammathur/setup-php@v2
+              with:
+                php-extension: '7.4'
+
+            - name: Install Composer dependencies
+              run: composer install
+
+            - name: Run PHPUnit
+              run: ./vendor/bin/phpunit --verbose
+
+    static-analysis:
+        name: Static Analysis using Phan
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v2
+
+            - name: Prepare PHP 7.4 with Phan
+              uses: shivammathur/setup-php@v2
+              with:
+                php-extension: '7.4'
+                tools: phan
+
+            - name: Install Composer dependencies
+              run: composer install
+
+            - name: Run Phan
+              run: phan

.gitignore

@@ -0,0 +1,4 @@
+/vendor/
+
+# Caches
+/.phpunit.result.cache

.phan/config.php

@@ -0,0 +1,14 @@
+<?php
+
+return [
+    'target_php_version' => '7.4',
+    'directory_list' => [
+        'src/',
+        'vendor/phan/phan/src/Phan',
+        'vendor/symfony/filesystem',
+    ],
+    'exclude_analysis_directory_list' => [
+        'vendor/',
+    ],
+    'color_issue_messages_if_supported' => true,
+];

README.md

@@ -0,0 +1,99 @@
+# Phirs
+
+A library providing platform-specific user directory paths, such as config and cache. Inspired by [dirs-rs](https://github.com/dirs-dev/dirs-rs).
+
+## Features
+
+-   **Multiple Platform.** Providing cross-platform paths, plus platform-specific ones. Make your app run-everywhere or target a specific platform. See [Platform Support](#platform-support) for more details.
+
+-   **Hackable.** Adding support for a specific platform [is easy](./docs/en/usage-guide.md#example-android-platform-support).
+
+-   **Well-Designed.** Provide good design and simple abstractions (with the help of powerful PHP interfaces and traits).
+
+-   **Well-Tested.** Many pieces of the library are covered by unit tests. With the help of CI tools also, it is continuously tested againts major platforms.
+
+## Why?
+
+When writing a console application (or even a graphical one; who knows, people might start writing graphical applications in PHP in near future), sometimes you need to have a location to:
+
+-   store your configurations, and possibly re-use them in the future runs,
+-   make cache files and improve the performance of your application,
+-   create a media and put it somewhere reasonable,
+-   etc.
+
+For the best results, the locations should be cross-platform, permanent, accessible (i.e. both readable and writable), well-known and non-relative.
+
+Phirs can help you in these situations.
+
+**Note:** The library does not guarantee that all provided paths meet all the conditions above, although it helps you achieving them. The reason is performance, and the fact that different users may have different needs (e.g. one may check for a path to exist, one may suppose it to exist). Theoretically, in a standard environment and for standard paths, all these conditions are met (although the directories might not actually exist).
+
+### But There Is Another Library!
+
+Why not just using [Basedir](https://github.com/clue-labs/php-basedir)?
+
+Go back and see [features](#features). Having these there would require a major rewrite and huge backward-compatibility break. Plus, Basedir is [no longer available on Packagist](https://packagist.org/search/?q=basedir), for some unknown reason.
+
+## Requirements
+
+PHP 7.4+ only.
+
+## Installation
+
+Easy like every other PHP library:
+
+```
+composer install machitgarha/phirs
+```
+
+## Basic Usage
+
+A simple use for most common cases is the following:
+
+```php
+use MAChitgarha\Phirs\DirectoryProviderFactory;
+use MAChitgarha\Phirs\Util\Platform;
+
+// Get a provider for the current platform
+$dirProvider = DirectoryProviderFactory::createStandard(Platform::autoDetect());
+
+// Let's get some paths!
+$configPath = $dirProvider->getConfigPath();
+$docsPath = $dirProvider->getDocumentsPath();
+
+// Load or save something…!
+```
+
+What a provider is? Why we use `createStandard()`? Can I extend it and map a specific platform to my own provider? See [Usage Guide](./docs/en/usage-guide.md) for more details.
+
+## Platform Support
+
+|Platform|Having a Provider?|Supported?|Working?|Having a Specialized Provider?|
+|:-:|:-:|:-:|:-:|:-:|
+|GNU/Linux distributions|✅|✅|✅|✅|
+|Windows|✅|✅|✅|✅|
+|Mac OS|✅|✅|✅|✅|
+|[Termux](https://termux.com) on Android|✅|✅|✅❕(1)|❌|
+|BSD|✅|❌|❔|❌|
+|Solaris|✅|❌|❔|❌|
+|Android|✅|❌|❓|❌|
+|iOS|✅|❌|❔|❌|
+
+-   ❕: Has notes.
+-   ❔: Not known or depends on the environment.
+-   ❓: Like ❔, but most likely no.
+
+### Notes
+
+1.  It might not be exactly what you or users expect; e.g. pictures directory path is inside Termux home, not the internal SDCard (i.e. `/sdcard`).
+
+## Contribute!
+
+In a world like this, everyone should be a contributor. So, start helping this project by creating an issue, forking and improving it, or simply introducing it to your PHP developer friends!
+
+If you want to get an overall overview of the code, go and read [Usage Guide](#usage-guide).
+
+For the best results, see [Contribution Guidelines](./.github/CONTRIBUTING.md).
+
+## License
+
+The project is licensed under [Apache 2.0 License](./LICENSE.md).

composer.json

@@ -0,0 +1,29 @@
+{
+    "name": "machitgarha/phirs",
+    "description": "Cross-platform user directory paths, such as config and cache",
+    "type": "library",
+    "license": "Apache-2.0",
+    "homepage": "https://github.com/machitgarha/phirs",
+    "authors": [
+        {
+            "name": "Mohammad Amin Chitgarha",
+            "email": "[email protected]",
+            "homepage": "https://github.com/machitgarha"
+        }
+    ],
+    "autoload": {
+        "psr-4": {
+            "MAChitgarha\\Phirs\\": "src/",
+            "MAChitgarha\\Phirs\\Test\\Unit\\": "tests/unit"
+        }
+    },
+    "require": {
+        "php": "^7.4|^8.0",
+        "symfony/filesystem": "5.4"
+    },
+    "require-dev": {
+        "php": "^7.4|^8.0",
+        "phan/phan": "^5.3",
+        "phpunit/phpunit": "^9.5"
+    }
+}