Merge pull request #300 from tightenco/jbk/language

Change whitelist and blacklist to only and except
tighten · Jun 26, 2020 · bc94fd1 · bc94fd1
2 parents d4d8735 + 7350264
commit bc94fd1
Show file tree

Hide file tree

Showing 7 changed files with 68 additions and 72 deletions.
diff --git a/README.md b/README.md
@@ -19,9 +19,9 @@ Ziggy supports all versions of Laravel from `5.4` to `7.x`.
     - [Examples](#examples)
     - [Default Values](#default-values)
 - [Filtering Routes](#filtering-routes)
-    - [Basic Whitelisting & Blacklisting](#basic-whitelisting--blacklisting)
-    - [Basic Whitelisting & Blacklisting using Macros](#basic-whitelisting--blacklisting-using-macros)
-    - [Advanced Whitelisting using Groups](#advanced-whitelisting-using-groups)
+    - [Basic Filtering](#basic-filtering)
+    - [Basic Filtering using Macros](#basic-filtering-using-macros)
+    - [Advanced Filtering using Groups](#advanced-filtering-using-groups)
 - [Other Useful Methods](#other-useful-methods)
     - [`current()`](#current)
     - [`check()`](#check)
@@ -123,50 +123,46 @@ Ziggy.defaultParameters = {
 
 Filtering routes is _completely optional_. If you want to pass all of your routes to your JavaScript by default, you can carry on using Ziggy as described above.
 
-#### Basic Whitelisting & Blacklisting
+#### Basic Filtering
 
-To take advantage of basic whitelisting or blacklisting of routes, you will first need to create a config file in your Laravel app at `config/ziggy.php` and define **either** a `whitelist` or `blacklist` setting as an array of route name patterns.
+To take advantage of basic route filtering, you can create a config file in your Laravel app at `config/ziggy.php` and define **either** an `only` or `except` setting as an array of route name patterns.
 
-**Note: You have to choose one or the other. Setting `whitelist` and `blacklist` will disable filtering altogether and simply return the default list of routes.**
+**Note: You have to choose one or the other. Setting both `only` and `except` will disable filtering altogether and simply return the default list of routes.**
 
 Example `config/ziggy.php`:
 
 ```php
 return [
-    // 'whitelist' => ['home', 'api.*'],
-    'blacklist' => ['debugbar.*', 'horizon.*', 'admin.*'],
+    // 'only' => ['home', 'api.*'],
+    'except' => ['debugbar.*', 'horizon.*', 'admin.*'],
 ];
 ```
 
 As shown in the example above, Ziggy can use asterisks as wildcards in route filter patterns. `home` will only match the route named `home`, whereas `api.*` will match any route whose name begins with `api.`, such as `api.posts.index` and `api.users.show`.
 
-#### Basic Whitelisting & Blacklisting using Macros
+#### Basic Filtering using Macros
 
-Whitelisting and blacklisting can also be achieved using the following macros.
-
-Example whitelisting:
+You can also filter routes using the following macros:
 
 ```php
-Route::whitelist(function () {
+Route::only(function () {
     Route::get('...')->name('posts');
 });
 
-Route::whitelist()->get('...')->name('posts');
+Route::only()->get('...')->name('posts');
 ```
 
-Example blacklisting:
-
 ```php
-Route::blacklist(function () {
+Route::except(function () {
     Route::get('...')->name('posts');
 });
 
-Route::blacklist()->get('...')->name('posts');
+Route::except()->get('...')->name('posts');
 ```
 
-#### Advanced Whitelisting using Groups
+#### Advanced Filtering using Groups
 
-You may also optionally define multiple whitelists using a `groups` key in your `config/ziggy.php`:
+You can also optionally define multiple groups of included routes using a `groups` key in your `config/ziggy.php`:
 
 ```php
 return [
@@ -182,7 +178,7 @@ return [
 ];
 ```
 
-In the above example, you can see we have configured multiple whitelists for different user roles. You may expose a specific whitelist group by passing the group key into the `@routes` directive in your Blade view:
+In the above example, we have configured multiple route groups for different user roles. You can expose a specific group by passing the group key into the `@routes` directive in your Blade view:
 
 ```php
 @routes('author')
@@ -194,7 +190,7 @@ If you want to expose multiple groups you can pass an array of group names:
 @routes(['admin', 'author'])
 ```
 
-**Note: Passing group names to the `@routes` directive will always take precedence over your other `whitelist` and `blacklist` settings.**
+**Note: Passing group names to the `@routes` directive will always take precedence over your other `only` or `except` settings.**
 
 ## Other Useful Methods
 

diff --git a/src/Macro.php b/src/Macro.php
@@ -6,8 +6,8 @@
 
 class Macro
 {
-    const BLACKLIST = 'blacklist';
-    const WHITELIST = 'whitelist';
+    const EXCEPT = 'except';
+    const ONLY = 'only';
 
     public function __construct(Router $router, $list, $group = null)
     {
@@ -25,26 +25,26 @@ public function compile()
         return $this;
     }
 
-    public static function whitelist(Router $router, $group = null)
+    public static function only(Router $router, $group = null)
     {
-        return (new static($router, static::WHITELIST, $group))->compile();
+        return (new static($router, static::ONLY, $group))->compile();
     }
 
-    public static function blacklist(Router $router, $group = null)
+    public static function except(Router $router, $group = null)
     {
-        return (new static($router, static::BLACKLIST, $group))->compile();
+        return (new static($router, static::EXCEPT, $group))->compile();
     }
 
     public function __call($method, $parameters)
     {
         $route = call_user_func_array([$this->router, $method], $parameters);
 
         switch ($this->list) {
-            case static::BLACKLIST:
-                $route->listedAs = 'blacklist';
+            case static::EXCEPT:
+                $route->listedAs = 'except';
                 break;
-            case static::WHITELIST:
-                $route->listedAs = 'whitelist';
+            case static::ONLY:
+                $route->listedAs = 'only';
                 break;
         }
 

diff --git a/src/RoutePayload.php b/src/RoutePayload.php
@@ -28,16 +28,16 @@ public function applyFilters($group)
         }
 
         // return unfiltered routes if user set both config options.
-        if (config()->has('ziggy.blacklist') && config()->has('ziggy.whitelist')) {
+        if (config()->has('ziggy.except') && config()->has('ziggy.only')) {
             return $this->routes;
         }
 
-        if (config()->has('ziggy.blacklist')) {
-            return $this->blacklist();
+        if (config()->has('ziggy.except')) {
+            return $this->except();
         }
 
-        if (config()->has('ziggy.whitelist')) {
-            return $this->whitelist();
+        if (config()->has('ziggy.only')) {
+            return $this->only();
         }
 
         return $this->routes;
@@ -60,14 +60,14 @@ public function group($group)
         return $this->routes;
     }
 
-    public function blacklist()
+    public function except()
     {
-        return $this->filter(config('ziggy.blacklist'), false);
+        return $this->filter(config('ziggy.except'), false);
     }
 
-    public function whitelist()
+    public function only()
     {
-        return $this->filter(config('ziggy.whitelist'), true);
+        return $this->filter(config('ziggy.only'), true);
     }
 
     public function filter($filters = [], $include = true)
@@ -87,10 +87,10 @@ protected function nameKeyedRoutes()
     {
         return collect($this->router->getRoutes()->getRoutesByName())
             ->map(function ($route) {
-                if ($this->isListedAs($route, 'blacklist')) {
-                    $this->appendRouteToList($route->getName(), 'blacklist');
-                } elseif ($this->isListedAs($route, 'whitelist')) {
-                    $this->appendRouteToList($route->getName(), 'whitelist');
+                if ($this->isListedAs($route, 'except')) {
+                    $this->appendRouteToList($route->getName(), 'except');
+                } elseif ($this->isListedAs($route, 'only')) {
+                    $this->appendRouteToList($route->getName(), 'only');
                 }
 
                 return collect($route)->only(['uri', 'methods'])

diff --git a/src/ZiggyServiceProvider.php b/src/ZiggyServiceProvider.php
@@ -10,12 +10,12 @@ class ZiggyServiceProvider extends ServiceProvider
 {
     public function boot()
     {
-        Route::macro('blacklist', function ($group = null) {
-            return Macro::blacklist($this, $group);
+        Route::macro('except', function ($group = null) {
+            return Macro::except($this, $group);
         });
 
-        Route::macro('whitelist', function ($group = null) {
-            return Macro::whitelist($this, $group);
+        Route::macro('only', function ($group = null) {
+            return Macro::only($this, $group);
         });
 
         if ($this->app->resolved('blade.compiler')) {

diff --git a/tests/Unit/CommandRouteGeneratorTest.php b/tests/Unit/CommandRouteGeneratorTest.php
@@ -64,7 +64,7 @@ function file_is_created_with_a_custom_url()
     function file_is_created_with_the_expected_group()
     {
         app()['config']->set('ziggy', [
-            'blacklist' => ['admin.*'],
+            'except' => ['admin.*'],
 
             'groups' => [
                 'admin' => ['admin.*'],

diff --git a/tests/Unit/MacroTest.php b/tests/Unit/MacroTest.php
@@ -9,11 +9,11 @@
 class MacroTest extends TestCase
 {
     /** @test */
-    function only_matching_routes_excluded_with_blacklist_group_are_filtered()
+    function only_matching_routes_excluded_with_except_group_are_filtered()
     {
         $router = app('router');
 
-        $router->blacklist(function ($router) {
+        $router->except(function ($router) {
             $router->get('/posts', function () { return ''; });
             $router->get('/posts/show', function () { return ''; })
                 ->name('posts.show');
@@ -30,13 +30,13 @@ function only_matching_routes_excluded_with_blacklist_group_are_filtered()
     }
 
     /** @test */
-    function only_matching_routes_excluded_with_blacklist_fluent_method_are_filtered()
+    function only_matching_routes_excluded_with_except_fluent_method_are_filtered()
     {
         $router = app('router');
 
         $router->get('/', function () { return ''; });
 
-        $router->blacklist()
+        $router->except()
             ->get('/pages', function () { return ''; })
             ->name('pages.index');
 
@@ -51,13 +51,13 @@ function only_matching_routes_excluded_with_blacklist_fluent_method_are_filtered
     }
 
     /** @test */
-    function only_matching_routes_excluded_with_blacklist_fluent_method_and_group_are_filtered()
+    function only_matching_routes_excluded_with_except_fluent_method_and_group_are_filtered()
     {
         $router = app('router');
 
         $router->get('/', function () { return ''; });
 
-        $router->blacklist(function ($router) {
+        $router->except(function ($router) {
             $router->get('/posts', function () { return ''; });
             $router->get('/posts/show', function () { return ''; })
                 ->name('posts.show');
@@ -66,7 +66,7 @@ function only_matching_routes_excluded_with_blacklist_fluent_method_and_group_ar
         $router->get('/tags/{tag}', function () { return ''; })
                 ->name('tags.show');
 
-        $router->blacklist()
+        $router->except()
             ->get('/pages', function () { return ''; })
             ->name('pages.index');
 
@@ -81,14 +81,14 @@ function only_matching_routes_excluded_with_blacklist_fluent_method_and_group_ar
     }
 
     /** @test */
-    function only_matching_routes_included_with_whitelist_fluent_method_are_filtered()
+    function only_matching_routes_included_with_only_fluent_method_are_filtered()
     {
         $router = app('router');
 
         $router->get('/tags/{tag}', function () { return ''; })
                 ->name('tags.show');
 
-        $router->whitelist()
+        $router->only()
             ->get('/pages', function () { return ''; })
             ->name('pages.index');
 
@@ -100,13 +100,13 @@ function only_matching_routes_included_with_whitelist_fluent_method_are_filtered
     }
 
     /** @test */
-    function only_matching_routes_included_with_whitelist_group_method_are_filtered()
+    function only_matching_routes_included_with_only_group_method_are_filtered()
     {
         $router = app('router');
 
         $router->get('/', function () { return ''; });
 
-        $router->whitelist(function ($router) {
+        $router->only(function ($router) {
             $router->get('/posts', function () { return ''; });
             $router->get('/posts/show', function () { return ''; })
                 ->name('posts.show');
@@ -123,13 +123,13 @@ function only_matching_routes_included_with_whitelist_group_method_are_filtered(
     }
 
     /** @test */
-    function only_matching_routes_included_with_whitelist_group_and_fluent_method_are_filtered()
+    function only_matching_routes_included_with_only_group_and_fluent_method_are_filtered()
     {
         $router = app('router');
 
         $router->get('/', function () { return ''; });
 
-        $router->whitelist(function ($router) {
+        $router->only(function ($router) {
             $router->get('/posts', function () { return ''; });
             $router->get('/posts/show', function () { return ''; })
                 ->name('posts.show');
@@ -138,7 +138,7 @@ function only_matching_routes_included_with_whitelist_group_and_fluent_method_ar
         $router->get('/tags/{tag}', function () { return ''; })
                 ->name('tags.show');
 
-        $router->whitelist()
+        $router->only()
             ->get('/pages', function () { return ''; })
             ->name('pages.index');
 

diff --git a/tests/Unit/RoutePayloadTest.php b/tests/Unit/RoutePayloadTest.php
@@ -48,7 +48,7 @@ public function setUp(): void
     }
 
     /** @test */
-    public function only_matching_routes_included_with_whitelist_enabled()
+    public function only_matching_routes_included_with_include_enabled()
     {
         $routePayload = new RoutePayload($this->router);
         $filters = ['posts.s*', 'home'];
@@ -76,7 +76,7 @@ public function only_matching_routes_included_with_whitelist_enabled()
     }
 
     /** @test */
-    public function only_matching_routes_excluded_with_blacklist_enabled()
+    public function only_matching_routes_excluded_with_exclude_enabled()
     {
         $routePayload = new RoutePayload($this->router);
         $filters = ['posts.s*', 'home', 'admin.*'];
@@ -99,10 +99,10 @@ public function only_matching_routes_excluded_with_blacklist_enabled()
     }
 
     /** @test */
-    public function existence_of_whitelist_config_causes_routes_to_whitelist()
+    public function existence_of_only_config_causes_routes_to_be_included()
     {
         app()['config']->set('ziggy', [
-            'whitelist' => ['posts.s*', 'home'],
+            'only' => ['posts.s*', 'home'],
         ]);
 
         $routes = RoutePayload::compile($this->router);
@@ -129,10 +129,10 @@ public function existence_of_whitelist_config_causes_routes_to_whitelist()
     }
 
     /** @test */
-    public function existence_of_blacklist_config_causes_routes_to_blacklist()
+    public function existence_of_except_config_causes_routes_to_be_excluded()
     {
         app()['config']->set('ziggy', [
-            'blacklist' => ['posts.s*', 'home', 'admin.*'],
+            'except' => ['posts.s*', 'home', 'admin.*'],
         ]);
 
         $routes = RoutePayload::compile($this->router);
@@ -157,8 +157,8 @@ public function existence_of_blacklist_config_causes_routes_to_blacklist()
     public function existence_of_both_configs_returns_unfiltered_routes()
     {
         app()['config']->set('ziggy', [
-            'blacklist' => ['posts.s*'],
-            'whitelist' => ['home'],
+            'except' => ['posts.s*'],
+            'only' => ['home'],
         ]);
 
         $routes = RoutePayload::compile($this->router);