updating docs; clearing buffer on file route; fix typo

2amigos · Dec 12, 2023 · dcb2909 · dcb2909
1 parent 50654ea
commit dcb2909
Show file tree

Hide file tree

Showing 6 changed files with 181 additions and 8 deletions.
diff --git a/docs/index.md b/docs/index.md
@@ -15,9 +15,15 @@ it uses a modified version of its code for the writers included on this package.
 
 ## Getting Started
 
+### Supported PHP Versions  
+| Tag | PHP Version |
+| :---: |:----------:|
+| ^ 3.0.2 |  7.3 - 8.0 |
+| 3.1.0 |  7.4 - 8.1 |
+
 ### Server Requirements
 
-- PHP >= 7.3
+- PHP >= 7.4
 - Imagick
 - GD
 - FreeType
@@ -27,12 +33,15 @@ The preferred way to install this extension is through [composer](http://getcomp
 Either run
 
 ```
-php composer.phar require 2amigos/qrcode-library:^3
+php composer.phar require 2amigos/qrcode-library:^3.1.0
 ```
 or add
 
 ```json
-    "2amigos/qrcode-library": "^3"
+{
+  ...
+  "2amigos/qrcode-library": "^3.1.0"
+}
 ```
 
 ### Usage 
@@ -72,11 +81,13 @@ You can set the foreground color, defining RGBA values, where the alpha is optio
 $qrCode = (new QrCode('This is my text'))
     ->setForeground(0, 0, 0);
 
-// or, setting alpha too
+// or, setting alpha as well
 $qrCode = (new QrCode('This is my text'))
     ->setForeground(0, 0, 0, 50);
 ```
 
+### Formats
+
 In order to ease the task to write different formats into a QrCode, the library comes with a set of classes. These are: 
 
 -  [BookmarkFormat](formats/bookmark.md)
@@ -93,6 +104,15 @@ In order to ease the task to write different formats into a QrCode, the library
 -  [WifiFormat](formats/wifi.md)
 -  [YoutubeFormat](formats/youtube.md)
 
+Laravel
+----
+
+This library bundles a blade component and a file route to easily work with the Laravel framework.
+
+- [LaravelBladeComponent](laravel/blade-component.md)
+- [File Route](laravel/file-route.md)
+- [Customization](laravel/customization.md)
+
 Yii2 
 ----
 

diff --git a/docs/laravel/blade-component.md b/docs/laravel/blade-component.md
@@ -0,0 +1,89 @@
+Laravel Blade Component
+----
+
+This library realeases a blade component to make it easy to build qrcode with the Laravel Framework.
+
+Before get started, make sure you have the class `\Da\QrCode\Providers\QrCodeServiceProvider::class`
+listed on you config/app.php file, on providers section.
+
+```php
+[
+    ...
+    'providers' => [
+        ...
+        \Da\QrCode\Providers\QrCodeServiceProvider::class,
+    ],
+];
+```
+
+With the provider set, we can create a qrcode using the `2am-qrcode` blade component.
+It has only `content` as a required field.
+
+```html
+<x-2am-qrcode :content="'2am. Technologies'"/>
+```
+
+We can also define the qrcode [format](../index.md#Formats). To do so,
+you must specify the `format` attribute with a constant from `\Da\QrCode\Enum\Format` and the `content` as an array,
+fulfilling the data for the designed format as specified in the format [docs]((../index.md#Formats)).
+
+To work with colors (background, foreground and gradient foreground), you set
+the attributes `background`, `foregroud` and `foreground2` (for gradient foreground) as an array
+having the keys `r`, `g`, `b` (and `a` to set alpha on foreground, but it's optional).
+
+```php
+$background = [
+    'r' => 200,
+    'g' => 200,
+    'b' => 200,
+];
+
+$foreground = [
+    'r' => 0,
+    'b' => 255,
+    'g' => 0,
+];
+
+$foreground2 = [
+    'r' => 0,
+    'b' => 0,
+    'g' => 255,
+];
+
+$content = [
+    'title' => '2am. Technologies',
+    'url' => 'https://2am.tech',
+];
+```
+
+```html
+<x-2am-qrcode
+    :content="$content"
+    :format="\Da\QrCode\Enums\Format::BOOK_MARK"
+    :background="$background"
+    :foreground="$foreground"
+    :foreground2="$foreground2"
+/>
+```
+
+All blade component attributes:
+
+| Attribute |                                Description                                 |                   Data Type                    |
+|:---------:|:--------------------------------------------------------------------------:|:----------------------------------------------:|
+|  content  |                         Defines the qrcode's data                          |                 string; array                  |
+| format |                        Defines the qrcode's format                         |             \Da\QrCode\Enum\Format             |
+| foreground |                 Defines the qrcode`s foreground base color                 |               array (r, g, b, a)               |
+| background |                   Defines the qrcode's background color                    |               array (r, g, b, a)               |
+| foreground2 |       Defines the qrcode's foreground end color (turns to gradient)        |               array (r, g, b, a)               |
+| pathStyle |                      Defines the qrcode's path style                       |              \Da\QrCode\Enum\Path              |
+| intensity |                      Defines the path style intensity                      |              float, from 0.1 to 1              |
+| margin |                        Defines the qrcode's margin                         |                      int                       |
+| size |                         Defines the qrcode's size                          |                      int                       |
+| logoPath |             Set a image to be displayed in the qrcode's center             |         string; it should be full path         |
+| logoSize |                        Set the qrcode's logo size.                         | int. Recomended size is 16% from qrcode's size |
+| scaleLogoHeight | Set if the logo's image should be scaled instead of croped to square shape |             bool. Default is false             |
+| gradientType |                         Defines the gradient type                          |           \Da\QrCode\Enums\Gradient            | 
+| label |                         Defines the qrcode's label                         | string |
+| font |                           Defines the label font                           | string. It should be full path |
+| fontSize |                        Defines the label font size                         | int |
+| fontAlign | Defines the label alignment | \Da\QrCode\Label |
diff --git a/docs/laravel/customization.md b/docs/laravel/customization.md
@@ -0,0 +1,18 @@
+Laravel Blade Component
+----
+
+You can publish the qrcode's config file by executing the given command:
+
+```bash
+$ php artisan vendor:publish --tag=2am-qrcode-config
+```
+
+This will create a file name 2am-qrcode.php under your config folder, where you can
+set the default look of your qrcode and the component prefix.
+
+By the next command, you can publish the component related view, enabling you to perform your
+own customization to component structure.
+
+```bash
+$ php artisan vendor:publish --tag=2am-qrcode-views
+```
diff --git a/docs/laravel/file-route.md b/docs/laravel/file-route.md
@@ -0,0 +1,44 @@
+Laravel File Route
+----
+
+This library realeases a blade component to make it easy to build qrcode with the Laravel Framework.
+
+Before get started, make sure you have the class `\Da\QrCode\Providers\QrCodeServiceProvider::class`
+listed on you config/app.php file, on providers section.
+
+```php
+[
+    ...
+    'providers' => [
+        ...
+        \Da\QrCode\Providers\QrCodeServiceProvider::class,
+    ],
+];
+```
+
+The file route is registered as `/da-qrcode/build` and it has only one required parameter: `content`.
+
+You can test this resource by accessing the endpoint, e.g `/da-qrcode/build?content=2am. Technologies` 
+
+As optional parameters it has:
+
+- label;
+- margin; and
+- size
+
+Here is a complete sample of usage:
+
+```html
+<img src="/da-qrcode/build?content=2am.%20Technologies&margin=25&size=500&label=2am.%20Technologies"/>
+
+<!-- or -->
+<img src="{{route(
+    'da-qrcode.build',
+    [
+        'content' => '2am ',
+        'size' => 500,
+        'margin' => 25,
+        'label' => '2am. Technologies'
+    ])}}"
+/>
+```
diff --git a/src/Controllers/LaravelResourceController.php b/src/Controllers/LaravelResourceController.php
@@ -16,6 +16,8 @@ final class LaravelResourceController
      */
     public function __invoke(Request $request)
     {
+        ob_end_clean();
+
         $data = $request->only([
             'content',
             'label',

diff --git a/src/Providers/QrCodeServiceProvider.php b/src/Providers/QrCodeServiceProvider.php
@@ -14,18 +14,18 @@ public function boot(): void
     {
         /** Load package views */
         $this->loadViewsFrom(__DIR__ . '/../../resources/views', '2am-qrcode');
-/** Load package routes */
+        /** Load package routes */
         $this->loadRoutesFrom(__DIR__ . '/../../routes/laravel.route.php');
-/** publishes package config */
+        /** publishes package config */
         $this->publishes([
             __DIR__ . '/../../config/2am-qrcode.php' => config_path('2am-qrcode.php'),
         ], '2am-qrcode-config');
         $this->publishes([
             __DIR__ . '/../../resources/views' => resource_path('views/vendor/2am-qrcode'),
         ], '2am-qrcode-views');
-/** merges config file with user's published version */
+        /** merges config file with user's published version */
         $this->mergeConfigFrom(__DIR__ . '/../../config/2am-qrcode.php', '2am-qrcode');
-/** Declares package's components */
+        /** Declares package's components */
         Blade::component('qrcode', QrCodeBladeComponent::class, config('2am-qrcode.prefix'));
     }
 }