init

.github/workflows/tests.yml

@@ -0,0 +1,36 @@
+name: Tests
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Set up PHP
+        uses: shivammathur/setup-php@15c43e89cdef867065b0213be354c2841860869e
+        with:
+          php-version: "8.2"
+
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Validate composer.json and composer.lock
+        run: composer validate --strict
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-interaction --no-progress
+
+      - name: Validate PHP PSR
+        run: composer run-script php-psr
+
+      - name: Run test suite
+        run: composer run-script test

.gitignore

@@ -0,0 +1,9 @@
+/vendor/
+/.phpunit.result.cache
+/phpunit.xml
+/composer.lock
+.idea/
+.vscode/*
+.githooks/*
+.TODO
+.php-cs-fixer.cache

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Multividas
+
+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.

README.md

@@ -0,0 +1,146 @@
+<div align="center">
+
+<img width="150" height="150" src="./assets/api-responser.svg" alt="API Responser package logo"/>
+
+# API Responser
+
+[![Tests](https://github.com/multividas/api-responser/actions/workflows/tests.yml/badge.svg)](https://github.com/multividas/api-responser/actions/workflows/tests.yml)
+[![Total Downloads](https://img.shields.io/packagist/dt/multividas/api-responser.svg?style=flat-square)](https://packagist.org/packages/multividas/api-responser)
+[![License](https://img.shields.io/github/license/multividas/api-responser?style=flat-square)](https://github.com/multividas/api-responser/blob/main/LICENSE)
+
+</div>
+
+composer package to facilitates the process of structuring and generating API responses
+
+## Installation
+Require this package with composer.
+
+```shell
+composer require multividas/api-responser 
+```
+
+## ServiceProvider:
+
+**[Optional]** Adding the **ApiResponserServiceProvider** to the providers array in **config/app.php**
+
+```php
+\Multividas\ApiResponser\Providers\ApiResponserServiceProvider::class,
+```
+
+**[Optional]** To get **X-Application-Name** http response header, Copy the package config to your local config with the publish command:
+
+```sh
+php artisan vendor:publish --tag=api-responser-config
+```
+
+## Usage
+
+```php
+use \Multividas\ApiResponser\Traits\ApiResponser;
+
+class Controller extends BaseController
+{
+    use ApiResponser;
+}
+```
+
+### Dependency Injection
+
+PostsController has __construct() method initializes a property apiRepository with an instance of the ApiRepositoryInterface.
+
+`showAll()` method receives **`Collection|JsonResource`** as its param.
+
+`showOne()` method receives **`Model|JsonResource $instance`** as its param.
+
+```php
+use \Multividas\ApiResponser\Interfaces\ApiRepositoryInterface;
+
+class PostsController extends Controller
+{
+    public function __construct(
+        public ApiRepositoryInterface $apiRepository
+    ) {
+    }
+
+    public function index(): JsonResponse
+    {
+        return $this->apiRepository->showAll(Post::all());
+    }
+
+    public function show(Post $post): JsonResponse
+    {
+        if (!$post instanceof Post) {
+            return $this->infoResponse('Item Not Found', 404, []);
+        }
+
+        return $this->apiRepository->showOne($post);
+    }
+}
+```
+
+### Facades
+
+Using the `ApiResponser` to access the methods of `ApiRepositoryInterface` in your `PostsController`.
+
+```php
+use Multividas\ApiResponser\Facades\ApiResponser;
+
+class PostsController extends Controller
+{
+    public function index(): JsonResponse
+    {
+        return ApiResponser::showAll(Post::all());
+    }
+
+    public function show(string $postId): JsonResponse
+    {
+        $post = Post::find($postId);
+
+        if (!$post instanceof Post) {
+            return $this->infoResponse('Post Not Found', 404, (object)[]);
+        }
+
+        return ApiResponser::showOne($post);
+    }
+}
+```
+
+This approach provides a cleaner and more organized way to interact with the `ApiRepositoryInterface` instance in your controller methods.
+
+### Success Response
+
+Successful response containing the requested data and an appropriate status code.
+
+```json
+{
+    "data": [],
+    "code": 200,
+    "meta": {}
+}
+```
+
+Learn more: [Multividas API Responser](https://developers.multividas.com/rest/introduction/api-responser)
+
+---
+
+### Run PHPUnit tests
+
+```sh
+composer test
+```
+
+## 🤝 Contributing
+
+Please read the [contributing guide](https://github.com/multividas/.github/blob/main/CONTRIBUTING.md).
+
+## 🛡️ Security Issues
+
+If you discover a security vulnerability within Multividas, we would appreciate your help in disclosing it to us responsibly, please check out our [security issues guidelines](https://github.com/multividas/.github/blob/main/SECURITY.md).
+
+## 🛡️ License
+
+Licensed under the [MIT license](https://github.com/multividas/.github/blob/main/LICENSE).
+
+---
+
+> Email: [email protected]

composer.json

@@ -0,0 +1,61 @@
+{
+    "name": "multividas/api-responser",
+    "type": "package",
+    "license": "MIT",
+    "description": "composer package to facilitates the process of structuring and generating API responses",
+    "keywords": [
+        "api-responser"
+    ],
+    "authors": [
+        {
+            "name": "Multividas",
+            "email": "[email protected]"
+        }
+    ],
+    "autoload": {
+        "psr-4": {
+            "Multividas\\ApiResponser\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Multividas\\ApiResponser\\Tests\\": "tests/"
+        }
+    },
+    "scripts": {
+        "test": "vendor/bin/phpunit tests/Feature",
+        "php-psr": [
+          "find src -type f -name \"*.php\" -print0 | xargs -0 -n1 php -lf",
+          "vendor/bin/php-cs-fixer fix --allow-risky=yes src --rules=declare_strict_types,@PSR12",
+          "./vendor/bin/phpcs --standard=PSR2 --encoding=utf-8 --extensions=php src/*"
+        ]
+    },
+    "require": {
+        "php": "^8.2"
+    },
+    "require-dev": {
+        "squizlabs/php_codesniffer": "4.0.x-dev",
+        "phpunit/phpunit": "9.6.x-dev",
+        "multividas/query-filters": "dev-main",
+        "orchestra/testbench": "8.x-dev",
+        "friendsofphp/php-cs-fixer": "dev-master"
+    },
+    "minimum-stability": "stable",
+    "config": {
+        "optimize-autoloader": true
+    },
+    "extra": {
+        "laravel": {
+            "providers": [
+                "Multividas\\ApiResponser\\Providers\\ApiResponserServiceProvider"
+            ],
+            "aliases": {
+                "ApiResponser": "Multividas\\ApiResponser\\Facades\\ApiResponser"
+            }
+        }
+    },
+    "support": {
+        "issues": "https://github.com/multividas/api-responser/issues",
+        "source": "https://github.com/multividas/api-responser"
+    }
+}

config/api-responser.php

@@ -0,0 +1,13 @@
+<?php
+
+/**
+ * (c) 2024 Multividas. All rights reserved.
+ * Unauthorized use prohibited.
+ * Website: https://www.multividas.com
+ */
+
+use Illuminate\Support\Env;
+
+return [
+    'app-name' => Env::get('APP_NAME', 'Api-Responser'),
+];

src/Facades/ApiResponser.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * (c) 2024 Multividas. All rights reserved.
+ * Unauthorized use prohibited.
+ * Website: https://www.multividas.com
+ */
+
+namespace Multividas\ApiResponser\Facades;
+
+use Illuminate\Support\Facades\Facade;
+use Multividas\ApiResponser\Interfaces\ApiRepositoryInterface;
+
+class ApiResponser extends Facade
+{
+    protected static function getFacadeAccessor(): string
+    {
+        return ApiRepositoryInterface::class;
+    }
+}

src/Interfaces/ApiRepositoryInterface.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * (c) 2024 Multividas. All rights reserved.
+ * Unauthorized use prohibited.
+ * Website: https://www.multividas.com
+ */
+
+namespace Multividas\ApiResponser\Interfaces;
+
+use Illuminate\Http\JsonResponse;
+use Illuminate\Support\Collection;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Http\Resources\Json\JsonResource;
+use Illuminate\Database\Eloquent\Collection as EloquentCollection;
+
+interface ApiRepositoryInterface
+{
+    public function showAll(
+        Collection|EloquentCollection|JsonResource $collection,
+        int $code = 200,
+        array $meta = []
+    ): JsonResponse;
+
+    public function listAll(
+        Collection|EloquentCollection|JsonResource $collection,
+        int $code = 200,
+        array $meta = []
+    ): JsonResponse;
+
+    public function showOne(
+        Model|JsonResource $instance,
+        int $code = 200,
+        array $meta = []
+    ): JsonResponse;
+}

src/Providers/ApiResponserServiceProvider.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * (c) 2024 Multividas. All rights reserved.
+ * Unauthorized use prohibited.
+ * Website: https://www.multividas.com
+ */
+
+namespace Multividas\ApiResponser\Providers;
+
+use Illuminate\Support\ServiceProvider;
+use Multividas\ApiResponser\Repositories\ApiRepository;
+use Multividas\ApiResponser\Interfaces\ApiRepositoryInterface;
+
+class ApiResponserServiceProvider extends ServiceProvider
+{
+    public function boot(): void
+    {
+        $this->publishes([
+            $this->basePath('config/api-responser.php') => base_path('config/api-responser.php')
+        ], 'api-responser-config');
+    }
+
+    public function register(): void
+    {
+        $this->mergeConfigFrom($this->basePath('config/api-responser.php'), 'api-responser');
+
+        $this->app->bind(ApiRepositoryInterface::class, function () {
+            return new ApiRepository();
+        });
+    }
+
+    protected function basePath($path = ""): string
+    {
+        return __DIR__ . '/../../' . $path;
+    }
+}