Core contracts (#70)

.github/CODEOWNERS

@@ -1,4 +1,6 @@
-# Packages
+/.github @JoshuaEstes
+/tools @JoshuaEstes
+/docs @JoshuaEstes
 /src/SonsOfPHP/Bard @JoshuaEstes
 /src/SonsOfPHP/Bridge/Doctrine/EventSourcing @JoshuaEstes
 /src/SonsOfPHP/Bridge/Doctrine/FeatureToggle @JoshuaEstes
@@ -30,3 +32,4 @@
 /src/SonsOfPHP/Component/PhoneNumber @JoshuaEstes
 /src/SonsOfPHP/Component/Queue @JoshuaEstes
 /src/SonsOfPHP/Component/Version @JoshuaEstes
+/src/SonsOfPHP/Contract/Core @JoshuaEstes

.github/labeler.yml

@@ -50,5 +50,9 @@ Version:
   - docs/components/version/*
   - src/SonsOfPHP/**/Version/*
 
+Contracts:
+  - docs/contracts/**
+  - src/SonsOfPHP/Contract/**
+
 documentation:
   - docs/**

CHANGELOG.md

@@ -26,6 +26,7 @@ Examples:
 * [PR #51](https://github.com/SonsOfPHP/sonsofphp/pull/51) Added new Filesystem component
 * [PR #59](https://github.com/SonsOfPHP/sonsofphp/pull/59) Added new HttpMessage component
 * [PR #59](https://github.com/SonsOfPHP/sonsofphp/pull/59) Added new HttpFactory component
+* [PR #70](https://github.com/SonsOfPHP/sonsofphp/pull/70) Added new Core contract
 
 ## [0.3.8]
 

bard.json

@@ -65,6 +65,10 @@
         {
             "path": "src/SonsOfPHP/Component/Version",
             "repository": "[email protected]:SonsOfPHP/version.git"
+        },
+        {
+            "path": "src/SonsOfPHP/Contract/Core",
+            "repository": "[email protected]:SonsOfPHP/core-contract.git"
         }
     ]
 }

docs/contracts/core/index.md

@@ -0,0 +1,19 @@
+---
+title: Core Contracts - Overview
+---
+
+# Core Contracts
+
+Core Contracts are generic contracts that are not specific to any one package or
+project.
+
+## Installation
+
+```shell
+composer require sonsofphp/core-contract
+```
+
+## Includes Interfaces
+
+* ComparableInterface
+* EquatableInterface

docs/contracts/index.md

@@ -0,0 +1,25 @@
+---
+title: Contracts
+---
+
+# Contracts
+
+Contracts are interfaces that can be reusable across multiple different
+libraries and projects. The actual implementation of the interfaces is left up
+to you.
+
+The interfaces also enhance existing PSRs.
+
+Whenever possible, the components and projects created by Sons of PHP will
+implement these interfaces.
+
+## Implementation
+
+If you want to provide a concrete library for others to use, add this to your
+`composer.json` file.
+
+```json
+    "provide": {
+        "sonsofphp/core-contract-implementation": "^1.0"
+    },
+```

mkdocs.yml

@@ -55,6 +55,8 @@ nav:
         - Getting Help: getting-help.md
         - Code of Conduct: code-of-conduct.md
         - Security Policy: security.md
+    - Bard:
+        - bard/index.md
     - Components:
         - components/index.md
         - Clock: components/clock/index.md
@@ -95,5 +97,6 @@ nav:
             - Operators: components/money/operators.md
             - Queries: components/money/queries.md
         - Version: components/version/index.md
-    - Bard:
-        - bard/index.md
+    - Contracts:
+        - contracts/index.md
+        - Core: contracts/core/index.md

src/SonsOfPHP/Contract/Core/.gitattributes

@@ -0,0 +1,2 @@
+/.gitattributes export-ignore
+/.gitignore export-ignore

src/SonsOfPHP/Contract/Core/.gitignore

@@ -0,0 +1,2 @@
+composer.lock
+vendor/

src/SonsOfPHP/Contract/Core/ComparableInterface.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Contract\Core;
+
+/**
+ * @author Joshua Estes <[email protected]>
+ */
+interface ComparableInterface
+{
+    /**
+     * Returns -1 if $this  <  $other
+     * Returns  0 if $this === $other
+     * Returns  1 if $this  >  $other
+     *
+     * @param mixed $other
+     *
+     * @throws \RuntimeException When the two objects cannot be compared
+     */
+    public function compare($other): int;
+}

src/SonsOfPHP/Contract/Core/EquatableInterface.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Contract\Core;
+
+/**
+ * Equatable Interface is used for objects that can be checked to see if they
+ * are equal to each other.
+ *
+ * @author Joshua Estes <[email protected]>
+ */
+interface EquatableInterface
+{
+    /**
+     * Checks object to see if it is equal to another object.
+     *
+     * @param mixed $other
+     * @param bool $strict
+     *   When true, this MUST compare objects using === and when false objects
+     *   MUST be compared using ==
+     *
+     * @throws \InvalidArgumentException
+     *   If $other is unexpected type
+     *
+     * @throws \RuntimeException
+     *   When it cannot be determined if the objects are equal to each other
+     */
+    public function equals($other, bool $strict = true): bool;
+}

src/SonsOfPHP/Contract/Core/LICENSE

@@ -0,0 +1,19 @@
+Copyright 2022 to Present Joshua Estes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/SonsOfPHP/Contract/Core/README.md

@@ -0,0 +1,20 @@
+Sons of PHP - Core Contract
+===========================
+
+Core Contracts include very generic interfaces that can be used across many
+different libraries. These would be the missing PHP interfaces that would be
+helpful.
+
+## Learn More
+
+* [Documentation][docs]
+* [Contributing][contributing]
+* [Report Issues][issues] and [Submit Pull Requests][pull-requests] in the [Mother Repository][mother-repo]
+* Get Help & Support using [Discussions][discussions]
+
+[discussions]: https://github.com/orgs/SonsOfPHP/discussions
+[mother-repo]: https://github.com/SonsOfPHP/sonsofphp
+[contributing]: https://docs.sonsofphp.com/contributing/
+[docs]: https://docs.sonsofphp.com/components/http-message/
+[issues]: https://github.com/SonsOfPHP/sonsofphp/issues?q=is%3Aopen+is%3Aissue+label%3ACore
+[pull-requests]: https://github.com/SonsOfPHP/sonsofphp/pulls?q=is%3Aopen+is%3Apr+label%3ACore

src/SonsOfPHP/Contract/Core/composer.json

@@ -0,0 +1,48 @@
+{
+    "name": "sonsofphp/core-contract",
+    "type": "library",
+    "description": "Core Contracts that are not specific to any one library",
+    "keywords": ["abstractions", "contracts", "decoupling", "interfaces", "interoperability", "standards"],
+    "homepage": "https://github.com/SonsOfPHP/core-contract",
+    "license": "MIT",
+    "authors": [
+        {
+            "name": "Joshua Estes",
+            "email": "[email protected]"
+        }
+    ],
+    "support": {
+        "issues": "https://github.com/SonsOfPHP/sonsofphp/issues",
+        "forum": "https://github.com/orgs/SonsOfPHP/discussions",
+        "docs": "https://docs.sonsofphp.com"
+    },
+    "autoload": {
+        "psr-4": {
+            "SonsOfPHP\\Contract\\Core\\": ""
+        },
+        "exclude-from-classmap": [
+            "/Tests/"
+        ]
+    },
+    "minimum-stability": "dev",
+    "prefer-stable": true,
+    "require": {
+        "php": ">=8.1"
+    },
+    "extra": {
+        "sort-packages": true,
+        "branch-alias": {
+            "dev-main": "0.3.x-dev"
+        }
+    },
+    "funding": [
+        {
+            "type": "github",
+            "url": "https://github.com/sponsors/JoshuaEstes"
+        },
+        {
+            "type": "tidelift",
+            "url": "https://tidelift.com/subscription/pkg/packagist-sonsofphp-sonsofphp"
+        }
+    ]
+}