refactor mlp docs

spatie · Feb 28, 2024 · 71f7486 · 71f7486
1 parent fad8e66
commit 71f7486
Show file tree

Hide file tree

Showing 8 changed files with 270 additions and 252 deletions.
diff --git a/.phpunit.cache/test-results b/.phpunit.cache/test-results
@@ -0,0 +1 @@
+{"version":"pest_2.34.0","defects":{"P\\Tests\\Conversions\\ConversionOrientationTest::__pest_evaluable_it_can_correctly_convert_an_image_with_orientation_exif_data":7},"times":{"P\\Tests\\Conversions\\ConversionOrientationTest::__pest_evaluable_it_can_correctly_convert_an_image_with_orientation_exif_data":0.123}}
diff --git a/docs/handling-uploads-with-media-library-pro/_index.md b/docs/handling-uploads-with-media-library-pro/_index.md
@@ -1,4 +1,4 @@
 ---
-title: Handling uploads with Media Library Pro
+title: Media Library Pro
 weight: 4
 ---
diff --git a/docs/handling-uploads-with-media-library-pro/customise.md b/docs/handling-uploads-with-media-library-pro/customise.md
@@ -0,0 +1,57 @@
+---
+title: Customise
+weight: 2
+---
+
+## Only allow authenticated users to upload files
+
+If in your project, you only want authenticated users to upload files, you can put the macro in a group that applies authentication middleware.
+
+```php
+Route::middleware('auth')->group(function() {
+    Route::mediaLibrary();
+});
+```
+
+We highly encourage you to do this, if you only need authenticated users to upload files.
+
+## Configure allowed mime types
+
+For security purposes, only files that pass [Laravel's `mimes` validation](https://laravel.com/docs/master/validation#rule-mimetypes) with the extensions [mentioned in this class](https://github.com/spatie/laravel-medialibrary-pro/blob/ba6eedd5b2a7f743909b441c0b6fd111d1a73794/src/Support/DefaultAllowedExtensions.php#L5) are allowed by the temporary upload controllers.
+
+If you want your components to accept other mimetypes, add a key `temporary_uploads_allowed_extensions` in the `media-library.php` config file.
+
+```php
+// in config/medialibrary.php
+
+return [
+   // ...
+
+   'temporary_uploads_allowed_extensions' => [
+        // your extensions
+        ... \Spatie\MediaLibraryPro\Support\DefaultAllowedExtensions::all(), // add this if you want to allow the default ones too
+   ],
+],
+]
+```
+
+## Rate limiting
+
+To protect you from users that upload too many files, the temporary uploads controllers are rate limited. By default, only 10 files can be upload per minute per ip iddress.
+
+To customize rate limiting, add [a rate limiter](https://laravel.com/docs/master/rate-limiting#introduction) named `medialibrary-pro-uploads`. Typically, this would be done in a service provider.
+
+Here's an example where's we'll allow 15 files:
+
+```php
+// in a service provider
+
+use Illuminate\Support\Facades\RateLimiter;
+
+RateLimiter::for('medialibrary-pro-uploads', function (Request $request) {
+    return [
+        Limit::perMinute(10)->by($request->ip()),
+    ];
+});
+```
+
diff --git a/docs/handling-uploads-with-media-library-pro/getting-started.md b/docs/handling-uploads-with-media-library-pro/getting-started.md
@@ -0,0 +1,10 @@
+---
+title: Getting started
+weight: 2
+---
+
+Things to do to get started:
+
+- Get a license
+- Install the package
+- Configure your frontend
diff --git a/docs/handling-uploads-with-media-library-pro/handling-uploads-with-vue.md b/docs/handling-uploads-with-media-library-pro/handling-uploads-with-vue.md
@@ -21,6 +21,38 @@ In [this repo on GitHub](https://github.com/spatie/laravel-medialibrary-pro-app)
 
 If you are having troubles using the components, take a look in that app to see how we've done it.
 
+## Setup Vite
+If you are using Vite, your `vite.config.js` look something like this:
+
+```js
+import { defineConfig } from 'vite';
+import laravel from 'laravel-vite-plugin';
+import vue from '@vitejs/plugin-vue';
+
+export default defineConfig({
+    resolve: {
+        alias: {
+            'media-library-pro': '/vendor/spatie/laravel-medialibrary-pro/resources/js',
+            'vue': 'vue/dist/vue.esm-bundler.js',
+        }
+    },
+    plugins: [
+        laravel([
+            'resources/js/app.js',
+        ]),
+        vue({
+            template: {
+                transformAssetUrls: {
+                    base: null,
+                    includeAbsolute: false,
+                },
+            },
+        }),
+    ],
+});
+
+```
+
 ## Basic setup
 
 First, the server needs to be able to catch your incoming uploads. Use the `mediaLibrary` macro in your routes file.
@@ -51,64 +83,14 @@ The Vue components post data to `/media-library-pro/uploads` by default. If you
 
 The components aren't available through npm, but are located in `vendor/spatie/laravel-medialibrary-pro/resources/js` when you install the package through Composer. This makes for very long import statements, which you can clean up by adding some configuration to your Webpack/Laravel Mix configuration.
 
-_If you're developing a project where you don't have access to composer, you can download the package through GitHub Packages: [installation steps](./installation#usage-in-a-frontend-repository)_
-
-**laravel-mix >6**
-
-```js
-// webpack.mix.js
-
-mix.override((webpackConfig) => {
-    webpackConfig.resolve.modules = [
-        "node_modules",
-        __dirname + "/vendor/spatie/laravel-medialibrary-pro/resources/js",
-    ];
-});
-```
-
-**laravel-mix <6**
-
-```js
-// webpack.mix.js
-
-mix.webpackConfig({
-    resolve: {
-        modules: [
-            "node_modules",
-            __dirname + "/vendor/spatie/laravel-medialibrary-pro/resources/js",
-        ],
-    },
-});
-```
-
-This will force Webpack to look in `vendor/spatie/laravel-medialibrary-pro/resources/js` when resolving imports, and allows you to shorten your import.
-
-```js
-import { MediaLibraryAttachment } from "media-library-pro-vue3-attachment";
-```
-
-If you're using TypeScript, you will also have to add this to your tsconfig:
-
-```json
-// tsconfig.json
-
-{
-    "compilerOptions": {
-        "paths": {
-            "*": ["*", "vendor/spatie/laravel-medialibrary-pro/resources/js/*"]
-        }
-    }
-}
-```
+_If you're developing a project where you don't have access to composer, you can download the package through GitHub Packages: [installation steps](./usage-in-a-frontend-repository)_
 
 To use a component in your Blade templates, import the components you plan to use in your `app.js` file, and add them to your main Vue app's `components` object.
 
-**Vue 3**
-
 ```js
 import { createApp } from "vue";
-import { MediaLibraryAttachment } from "media-library-pro-vue3-attachment";
-import { MediaLibraryCollection } from "media-library-pro-vue3-collection";
+import { MediaLibraryAttachment } from "media-library-pro/media-library-pro-vue3-attachment";
+import { MediaLibraryCollection } from "media-library-pro/media-library-pro-vue3-collection";
 
 createApp({
     components: {
@@ -146,8 +128,8 @@ You may also choose to import the components on the fly in a `.vue` file.
 </template>
 
 <script>
-    import { MediaLibraryAttachment } from "media-library-pro-vue3-attachment";
-    import { MediaLibraryCollection } from "media-library-pro-vue3-collection";
+    import { MediaLibraryAttachment } from "media-library-pro/media-library-pro-vue3-attachment";
+    import { MediaLibraryCollection } from "media-library-pro/media-library-pro-vue3-collection";
 
     export default {
         components: {
@@ -158,49 +140,6 @@ You may also choose to import the components on the fly in a `.vue` file.
 </script>
 ```
 
-## Vite
-If you are using vite, you need to import an alias to the `vite.config.js`  and some little changes to your Vue component.
-
-```diff
-// vite.config.js
-
-import { defineConfig } from 'vite';
-import laravel from 'laravel-vite-plugin';
-import vue from '@vitejs/plugin-vue';
-
-export default defineConfig({
-    ...
-    resolve: {
-        alias: {
-            '@': '/resources/js',
-+           'spatie-media-lib-pro': '/vendor/spatie/laravel-medialibrary-pro/resources/js',
-        },
-    },
-});
-```
-
-**Component changes Vue2**
-
-```diff
-...
--    import { MediaLibraryAttachment } from "media-library-pro-vue2-attachment";
-+    import { MediaLibraryAttachment } from "spatie-media-lib-pro/media-library-pro-vue2-attachment";
--    import { MediaLibraryCollection } from "media-library-pro-vue2-collection";
-+    import { MediaLibraryCollection } from "spatie-media-lib-pro/media-library-pro-vue2-collection";
-...
-```
-
-**Component changes Vue3**
-
-```diff
-...
--    import { MediaLibraryAttachment } from "media-library-pro-vue3-attachment";
-+    import { MediaLibraryAttachment } from "spatie-media-lib-pro/media-library-pro-vue3-attachment";
--    import { MediaLibraryCollection } from "media-library-pro-vue3-collection";
-+    import { MediaLibraryCollection } from "spatie-media-lib-pro/media-library-pro-vue3-collection";
-...
-```
-
 **CSS Import for SPA use**
 
 If you are using a SPA you can import the CSS into `app.js` like this:
@@ -209,7 +148,7 @@ If you are using a SPA you can import the CSS into `app.js` like this:
 // resources/js/app.js
 import './bootstrap';
 import '../css/app.css';
-+import 'spatie-media-lib-pro/media-library-pro-styles/src/styles.css';
++import 'media-library-pro/media-library-pro-styles/src/styles.css';
 ...
 ```
 
@@ -232,8 +171,8 @@ The most basic components have a `name` prop. This name will be used to identify
 </template>
 
 <script>
-    import { MediaLibraryAttachment } from "media-library-pro-vue3-attachment";
-    import { MediaLibraryCollection } from "media-library-pro-vue3-collection";
+    import { MediaLibraryAttachment } from "media-library-pro/media-library-pro-vue3-attachment";
+    import { MediaLibraryCollection } from "media-library-pro/media-library-pro-vue3-collection";
 
     export default {
         components: {