Add readme

onursimsek · Feb 3, 2024 · 08ae6d1 · 08ae6d1
1 parent 7e85d42
commit 08ae6d1
Show file tree

Hide file tree

Showing 4 changed files with 259 additions and 4 deletions.
diff --git a/README-tr.md b/README-tr.md
@@ -0,0 +1,131 @@
+# HTTP Precondition for Laravel
+
+[![Latest Version on Packagist](https://img.shields.io/packagist/v/onursimsek/precondition.svg?style=flat-square)](https://packagist.org/packages/onursimsek/precondition)
+[![MIT Licensed](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE.md)
+[![Tests](https://github.com/onursimsek/precondition/actions/workflows/run-tests.yml/badge.svg)](https://github.com/onursimsek/precondition/actions)
+[![Quality Score](https://img.shields.io/scrutinizer/g/onursimsek/precondition.svg?style=flat-square)](https://scrutinizer-ci.com/g/onursimsek/precondition)
+[![Total Downloads](https://img.shields.io/packagist/dt/onursimsek/precondition.svg?style=flat-square)](https://packagist.org/packages/onursimsek/precondition)
+
+## Kurulum
+
+Kurulum icin projenizde asagidaki komutu calistirin:
+
+```shell
+composer require onursimsek/precondition
+```
+
+## Kullanim
+
+Bir istemci sizden bir kaynagi istemis (GET), bir sure sonra kaynakta guncelleme yapip size geri gondermek (PUT) ister.
+O sirada baska bir istemci de ayni kaynagi almis (GET) ve ilk istemciden once guncellemistir (PUT). Bu durumda ilk
+istemcinin yapmis oldugu guncelleme yanlis bir kopya uzerinden olacaktir ve ikinci istemcinin yaptigi guncellemeleri
+gormezden gelecektir. Buna **[kayip guncelleme problemi](https://www.rfc-editor.org/rfc/rfc6585.txt)** denir.
+
+Boyle bir durumda ilk istemciye **[428 Precondition Required](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/428)** donusunde
+bulunarak, kaynagi tekrar cekmesini isteyebilirsiniz.
+
+Bu paket bu islemi kolayca yapmanizi saglar. Tek yapmaniz gereken bir **Validator class**'i olusturmak ve ilgili
+controller metoduna **attribute** olarak eklemek.
+
+```php
+use Illuminate\Http\Request;
+use OnurSimsek\Precondition\Validators\PreconditionValidator;
+
+class LostUpdateValidator extends PreconditionValidator
+{
+    public function parameter(Request $request)
+    {
+        return $request->header('If-Match');
+    }
+
+    public function __invoke(Request $request): bool
+    {
+        return $this->parameter($request) == $request->route('article')->updated_at;
+    }
+}
+```
+
+```php
+use App\Models\Article;
+use App\Http\Requests\UpdateArticleRequest;
+use OnurSimsek\Precondition\Attributes\Precondition;
+
+class ArticleController
+{
+    #[Precondition(LostUpdateValidator::class)]
+    public function update(Article $article, UpdateArticleRequest $request)
+    {
+        $article->fill($request->validated())
+        $article->save();
+
+        return response()->json();
+    }
+}
+```
+
+Bunun disinda bir istegin gerceklestirilmesi icin herhangi bir sartiniz varsa yine bu paketi kullanabilirsiniz. Iste
+bazi ornekler;
+
+### Github Ornegi
+
+Bir repo silinmeden once repo adinin tekrar yazilmasi istenir.
+
+```php
+use Illuminate\Http\Request;
+use OnurSimsek\Precondition\Validators\PreconditionValidator;
+
+class DeleteRepositoryValidator extends PreconditionValidator
+{
+    public function parameter(Request $request)
+    {
+        return $request->input('repository_name');
+    }
+
+    public function __invoke(Request $request): bool
+    {
+        return $this->parameter($request) == $request->route('repository')->name;
+    }
+}
+```
+
+**Not:** Repo adi dogru degilse, cevap 
+**[412 Precondition Failed](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412)** durum kodu ile doner.
+
+### SMS ile Dogrulama
+
+Odeme islemi yapilmadan once sms dogrulamasi yapilmak istenir.
+
+```php
+use Illuminate\Http\Request;
+use OnurSimsek\Precondition\Validators\PreconditionValidator;
+
+class SmsValidator extends PreconditionValidator
+{
+    public function preProcess(): void
+    {
+        cache()->set('sms', '123456');
+    }
+
+    public function parameter(Request $request)
+    {
+        return cache()->get('sms');
+    }
+
+    public function __invoke(Request $request): bool
+    {
+        return $this->parameter($request) == $request->input('sms_code');
+    }
+}
+```
+
+Hata mesajlarini ozellestirmek icin validator class'inda **messages()** metodunu kullanabilirsiniz.
+
+```php
+public function messages(): array
+{
+    return [
+        'required' => 'Telefonunuza gelen sms kodunu giriniz.',
+        'failed' => 'Sms kodunu dogru girmediniz!',
+    ];
+}
+```
diff --git a/README.md b/README.md
@@ -5,3 +5,126 @@
 [![Tests](https://github.com/onursimsek/precondition/actions/workflows/run-tests.yml/badge.svg)](https://github.com/onursimsek/precondition/actions)
 [![Quality Score](https://img.shields.io/scrutinizer/g/onursimsek/precondition.svg?style=flat-square)](https://scrutinizer-ci.com/g/onursimsek/precondition)
 [![Total Downloads](https://img.shields.io/packagist/dt/onursimsek/precondition.svg?style=flat-square)](https://packagist.org/packages/onursimsek/precondition)
+
+## Installation
+
+To install, run the following command in your project:
+
+```shell
+composer require onursimsek/precondition
+```
+
+## Usage
+
+A client has requested a resource from you (GET), and after a while wants to update the resource and send it back to
+you (PUT). Meanwhile, another client has received the same resource (GET) and updated it before the first client (PUT).
+In this case, the first client's update will be based on an incorrect copy and will ignore the second client's updates.
+This is called **[lost update problem](https://www.rfc-editor.org/rfc/rfc6585.txt)**.
+
+In such a case, you can return **[428 Precondition Required](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/428)** to the first
+client and ask it to pull the resource again.
+
+This package allows you to do this easily. All you need to do is create a **Validator class** and add it as an 
+**attribute** to the corresponding controller method.
+
+```php
+use Illuminate\Http\Request;
+use OnurSimsek\Precondition\Validators\PreconditionValidator;
+
+class LostUpdateValidator extends PreconditionValidator
+{
+    public function parameter(Request $request)
+    {
+        return $request->header('If-Match');
+    }
+
+    public function __invoke(Request $request): bool
+    {
+        return $this->parameter($request) == $request->route('article')->updated_at;
+    }
+}
+```
+
+```php
+use App\Models\Article;
+use App\Http\Requests\UpdateArticleRequest;
+use OnurSimsek\Precondition\Attributes\Precondition;
+
+class ArticleController
+{
+    #[Precondition(LostUpdateValidator::class)]
+    public function update(Article $article, UpdateArticleRequest $request)
+    {
+        $article->fill($request->validated())
+        $article->save();
+
+        return response()->json();
+    }
+}
+```
+
+You can also use this package if you have any conditions for a request to be fulfilled. For example some examples;
+
+### Github Sample
+
+You are prompted to re-type the repository name before deleting a repository.
+
+```php
+use Illuminate\Http\Request;
+use OnurSimsek\Precondition\Validators\PreconditionValidator;
+
+class DeleteRepositoryValidator extends PreconditionValidator
+{
+    public function parameter(Request $request)
+    {
+        return $request->input('repository_name');
+    }
+
+    public function __invoke(Request $request): bool
+    {
+        return $this->parameter($request) == $request->route('repository')->name;
+    }
+}
+```
+
+**Note:** If the repo name is invalid, the response returns with a status code of 
+**[412 Precondition Failed](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412)**.
+
+### SMS Verification
+
+SMS verification is a mandatory step in the payment process.
+
+```php
+use Illuminate\Http\Request;
+use OnurSimsek\Precondition\Validators\PreconditionValidator;
+
+class SmsValidator extends PreconditionValidator
+{
+    public function preProcess(): void
+    {
+        cache()->set('sms', '123456');
+    }
+
+    public function parameter(Request $request)
+    {
+        return cache()->get('sms');
+    }
+
+    public function __invoke(Request $request): bool
+    {
+        return $this->parameter($request) == $request->input('sms_code');
+    }
+}
+```
+
+You can use the **messages()** method in the validator class to customize the error messages.
+
+```php
+public function messages(): array
+{
+    return [
+        'required' => 'Enter the sms code sent to your phone.',
+        'failed' => 'Incorrect sms code!',
+    ];
+}
+```
diff --git a/tests/Unit/Attributes/PreconditionTest.php b/tests/Unit/Attributes/PreconditionTest.php
@@ -49,7 +49,7 @@ public function throw_precondition_failed_exception()
         $request->expects($this->exactly(2))
             ->method('header')
             ->with('If-Unmodified-Since')
-            ->willReturn((clone $updatedAt)->addYear());
+            ->willReturn((clone $updatedAt)->addYear()->format(DATE_RFC7231));
 
         $request->expects($this->once())
             ->method('route')
@@ -72,7 +72,7 @@ public function it_can_be_validate_a_proper_request()
         $request->expects($this->exactly(2))
             ->method('header')
             ->with('If-Unmodified-Since')
-            ->willReturn($updatedAt);
+            ->willReturn($updatedAt->format(DATE_RFC7231));
 
         $request->expects($this->once())
             ->method('route')

diff --git a/tests/Unit/Fixtures/LostUpdateValidator.php b/tests/Unit/Fixtures/LostUpdateValidator.php
@@ -5,17 +5,18 @@
 namespace OnurSimsek\Precondition\Tests\Unit\Fixtures;
 
 use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Date;
 use OnurSimsek\Precondition\Validators\PreconditionValidator;
 
 class LostUpdateValidator extends PreconditionValidator
 {
-    public function parameter(Request $request): array|string|null
+    public function parameter(Request $request)
     {
         return $request->header('If-Unmodified-Since');
     }
 
     public function __invoke(Request $request): bool
     {
-        return $this->parameter($request) == $request->route('article')->updated_at;
+        return Date::createFromFormat(DATE_RFC7231, $this->parameter($request)) == $request->route('article')->updated_at;
     }
 }