Merge pull request #37 from FarhanShares/docs-updates

Docs updates
FarhanShares · Apr 3, 2021 · c65531e · c65531e
2 parents 8fac0f4 + 1d4994f
commit c65531e
Show file tree

Hide file tree

Showing 2 changed files with 58 additions and 21 deletions.
diff --git a/README.md b/README.md
@@ -8,10 +8,9 @@
 </p>
 
 # Laravel MediaMan</h1>
-The most elegant & powerful media management package for Laravel!
-
-
+MediaMan is an elegant & powerful media management package for Laravel Apps with support for painless `uploader`, virtual `collection` & automatic `conversion` plus an on demand `association` with specific broadcasting `channel`s of your app models.
 
+MediaMan is UI agnostic & provides a fluent API to manage your app's media, which means you've total control over your media, the look & feel & a hassle free dev experience. It's a perfect suit for your App or API server.
 
 ## In a hurry? Here's a quick example:
 
@@ -21,7 +20,7 @@ $media = MediaUploader::source($request->file->('file'))
             ->upload();
 
 $post = Post::find(1);
-$post->attachMedia($media, 'featured-image');
+$post->attachMedia($media, 'featured-image-channel');
 ```
 
 
@@ -34,27 +33,35 @@ There are a few key concepts that need to be understood before continuing:
 
 * **MediaUploader**: Media items are uploaded as its own entity. It does not belong to any other model in the system when it's being created, so items can be managed independently (which makes it the perfect engine for a media manager). MediaMan provides "MediaUploader" for creating records in the database & storing in the filesystem as well.
 
-* **MediaCollection**: Media items can be bundled to any "collection". Media & Collections will form many-to-many relation. You can use it to create groups of media without really associating media to your App Models.
+* **MediaCollection**: Media items can be bundled to any "collection". Media & Collections will form many-to-many relation. You can create collections / virtual directories / groups of media & later on retrieve a group to check what it contains or do.
 
-* **Association**: Media need be attached to a model for an association to be made. MediaMan exposes helpers to easily get the job done. Many-to-many polymorphic relationships allow any number of media to be associated to any number of other models without the need of modifying their schema.
+* **Association**: Media items need be attached to a model for an association to be made. MediaMan exposes helpers to easily get the job done. Many-to-many polymorphic relationships allow any number of media to be associated to any number of other models without the need of modifying the existing database schema.
 
-* **Channel**: Media items are bound to a "channel" of a model during association. Thus you can easily associate multiple types of media to a model. For example, a "User" model might have an "avatar" and a "documents" media channel.
+* **Channel**: Media items are bound to a "channel" of a model during association. Thus you can easily associate multiple types of media to a model. For example, a "User" model might have an "avatar" and a "documents" media channel. If your head is spinning, simply think of "channels" as :tags" for a specific model. Channels are also needed to perform conversions.
 
-* **Conversion**: You can manipulate images using conversions, conversions will be performed when a media item (image) is associated to a model. For example, you can register a "thumbnail" conversion to run when images are attached to the "gallery" channel of a model.
+* **Conversion**: You can manipulate images using conversions, conversions will be performed when a media item is associated to a model. For example, you can register a "thumbnail" conversion to run when images are attached to the "gallery" channel of a model.
 
 
 
 
 ## Table of Contents
+  * [Requirements](#requirements)
   * [Installation](#installation)
   * [Configuration](#configuration)
   * [Media](#media)
   * [Media & Models](#media--models)
   * [Collections](#collections)
   * [Media & Collections](#media--collections)
   * [Media, Models & Conversions](#conversions)
+  * [What's unique?](#whats-unique-why-use-this-package)
+
 
 
+### Requirements
+
+- PHP v7.3 | v7.4 | v8.0
+- Laravel v7 | v8
+- Composer v1 | v2
 
 ## Installation
 
@@ -63,7 +70,7 @@ You can install the package via composer:
 ```bash
 composer require farhanshares/laravel-mediaman
 ```
-The package should be auto discovered by Laravel unless you've disabled auto-discovery mode. In that case, add the service provider to your config/app.php file:
+The package should be auto discovered by Laravel unless you've disabled auto-discovery mode. In that case, add the service provider to your config/app.php:
 
 `FarhanShares\MediaMan\MediaManServiceProvider::class`
 
@@ -80,19 +87,30 @@ php artisan migrate
 
 
 ## Configuration
-MediaMan works out of the box. If you want to tweak it, MediaMan ships with a config/mediaman.php. One common need of tweaking could be to store media in a dedicated Storage.
+MediaMan works out of the box. If you want to tweak it, MediaMan ships with a `config/mediaman.php`. One common need of tweaking could be to store media in a dedicated Storage.
+
+MediaMan supports all of the storage drivers that are supported by Laravel (for i.e. Local, S3, SFTP, FTP, Dropbox & so on).
 
-MediaMan supports all of the storage drivers that are supported by Laravel. For i.e. Let's configure a local media disk for MediaMan.
+Here's an example configuration to use a dedicated local media disk for MediaMan.
 
 ```php
 // file: config/filesystems.php
-// add the lines in the disks array
-'media' => [
-    'driver' => 'local',
-    'root' => storage_path('app/media'),
-    'url' => env('APP_URL') . '/media',
-    'visibility' => 'public',
-  ],
+// define a new disk
+'disks' => [
+    ...
+    'media' =>
+        'driver' => 'local',
+        'root' => storage_path('app/media'),
+        'url' => env('APP_URL') . '/media',
+        'visibility' => 'public',
+    ],
+]
+
+// define the symbolic link
+'links' => [
+    ...
+    public_path('media') => storage_path('app/media'),
+],
 
 
 // file: config/mediaman.php
@@ -471,5 +489,24 @@ $mediaOneThumb = $media[0]->getUrl('thumb');
 
 *Tip:* The `media_url` is always appended & it's the original media URL.
 
+
+### What's unique? Why use this package?
+
+Most of the Laravel app deals with media / files at some point of it's development cycle. I was enjoying [Spatie's Laravel MediaLibrary](https://github.com/spatie/laravel-medialibrary). Then I found [Optix's Laravel Media](https://github.com/optixsolutions/laravel-media), which is a good one too. Both has differences with pros & cons.
+
+I was searching for a solution to suit my needs & ended up developing the package. It's highly inspired from the above two packages. MediaMan is lightweight, elegant & featureful. It can be used as simple hassle-free media attachment-detachment solution for any model or it can be a powerful media manager's backend. It'll continue to receive updates whenever needed..
+
+
+| Comparison                        | Spatie              | Optix          | MediaMan            |
+|-----------------------------------|---------------------|----------------|---------------------|
+| **Relationship type**             | One to many         | Many to many   | **Many to many**    |
+| **Reuse media with another model**| No                  | Yes            | **Yes**             |
+| **Virtual directory**             | No                  | No             | **Yes**             |
+| **Auto delete media with model**  | Yes                 | No             | **Yes**             |
+| **Image manipulation**            | Yes                 | Yes            | **Yes**             |
+| **Manipulation type**             | Specific to a model | Global registry| **Global registry** |
+
+
+If you encounter a bug, please consider opening an issue. Feature Requests & PRs are welcome.
 ## License
 The MIT License (MIT). Please read [License File](LICENSE.md) for more information.
diff --git a/src/MediaUploader.php b/src/MediaUploader.php
@@ -125,7 +125,7 @@ public function toCollection(string $name)
      */
     public function setFileName(string $fileName)
     {
-        $this->fileName = $this->sanitiseFileName($fileName);
+        $this->fileName = $this->sanitizeFileName($fileName);
 
         return $this;
     }
@@ -140,12 +140,12 @@ public function useFileName(string $fileName)
     }
 
     /**
-     * Sanitise the file name.
+     * Sanitize the file name.
      *
      * @param string $fileName
      * @return string
      */
-    protected function sanitiseFileName(string $fileName)
+    protected function sanitizeFileName(string $fileName)
     {
         return str_replace(['#', '/', '\\', ' '], '-', $fileName);
     }