Merge pull request #8928 from ddevsr/docs-service

docs: replace `Services` class to `service()`

Author: kenjis

user_guide_src/source/concepts/services.rst

@@ -37,7 +37,7 @@ come in handy.
 Instead of creating the instance ourself, we let a central class create an instance of the
 class for us. This class is kept very simple. It only contains a method for each class that we want
 to use as a service. The method typically returns a **shared instance** of that class, passing any dependencies
-it might have into it. Then, we would replace our timer creation code with code that calls this new class:
+it might have into it. Then, we would replace our timer creation code with code that calls this global function or Services class:
 
 .. literalinclude:: services/002.php
 
@@ -55,7 +55,7 @@ As many CodeIgniter classes are provided as services, you can get them like the
 
 .. literalinclude:: services/013.php
 
-The ``$typography`` is an instance of the Typography class, and if you call ``\Config\Services::typography()`` again, you will get the exactly same instance.
+The ``$timer`` is an instance of the Timer class, and if you call ``service('timer')`` again, you will get the exactly same instance.
 
 The Services typically return a **shared instance** of the class. The following code creates a ``CURLRequest`` instance at the first call. And the second call returns the exactly same instance.
 
@@ -66,7 +66,7 @@ Therefore, the parameter ``$options2`` for the ``$client2`` does not work. It is
 Getting a New Instance
 ======================
 
-If you want to get a new instance of the Typography class, you need to pass ``false`` to the argument ``$getShared``:
+If you want to get a new instance of the Timer class, you need to pass ``false`` to the argument ``$getShared``:
 
 .. literalinclude:: services/014.php
 
@@ -85,6 +85,8 @@ always return the same instance:
 
 .. literalinclude:: services/003.php
 
+.. note:: Since v4.5.0, when you don't pass parameters to the service, the global function ``service()`` is recommended due to performance improvements.
+
 If the creation method requires additional parameters, they can be passed after the service name:
 
 .. literalinclude:: services/004.php

user_guide_src/source/concepts/services/002.php

@@ -1,3 +1,6 @@
 <?php
 
+$timer = service('timer');
+
+// The code above is the same as the code below.
 $timer = \Config\Services::timer();

user_guide_src/source/concepts/services/012.php

@@ -1,3 +1,3 @@
 <?php
 
-$postManager = \Config\Services::postManager();
+$postManager = service('postManager');

user_guide_src/source/concepts/services/013.php

@@ -1,3 +1,3 @@
 <?php
 
-$typography = \Config\Services::typography();
+$timer = service('timer');

user_guide_src/source/concepts/services/014.php

@@ -1,3 +1,3 @@
 <?php
 
-$typography = \Config\Services::typography(false);
+$timer = \Config\Services::timer(false);

user_guide_src/source/concepts/services/015.php

@@ -4,12 +4,12 @@
     'baseURI' => 'http://example.com/api/v1/',
     'timeout' => 3,
 ];
-$client1 = \Config\Services::curlrequest($options1);
+$client1 = service('curlrequest', $options1);
 
 $options2 = [
     'baseURI' => 'http://another.example.com/api/v2/',
     'timeout' => 10,
 ];
-$client2 = \Config\Services::curlrequest($options2);
+$client2 = service('curlrequest', $options2);
 // $options2 does not work.
 // $client2 is the exactly same instance as $client1.

user_guide_src/source/extending/basecontroller/003.php

@@ -18,6 +18,6 @@ public function initController(/* ... */)
         // Do Not Edit This Line
         parent::initController($request, $response, $logger);
 
-        $this->session = \Config\Services::session();
+        $this->session = service('session');
     }
 }

user_guide_src/source/general/common_functions.rst

@@ -372,7 +372,7 @@ Miscellaneous Functions
     :returns:    The shared Request object.
     :rtype:    IncomingRequest|CLIRequest
 
-    This function is a wrapper for ``Services::request()``.
+    This function is a wrapper for ``Services::request()`` and ``service('request')``.
 
 .. php:function:: response()
 
@@ -381,7 +381,7 @@ Miscellaneous Functions
     :returns:    The shared Response object.
     :rtype:    Response
 
-    This function is a wrapper for ``Services::response()``.
+    This function is a wrapper for ``Services::response()`` and ``service('response')``.
 
 .. php:function:: route_to($method[, ...$params])
 

user_guide_src/source/general/errors/018.php

@@ -1,6 +1,6 @@
 <?php
 
-$response = \Config\Services::response()
+$response = service('response')
     ->redirect('https://example.com/path')
     ->setHeader('Some', 'header')
     ->setCookie('and', 'cookie');

user_guide_src/source/incoming/content_negotiation/001.php

@@ -1,3 +1,3 @@
 <?php
 
-$negotiate = \Config\Services::negotiator();
+$negotiate = service('negotiator');

user_guide_src/source/incoming/incomingrequest/002.php

@@ -1,3 +1,3 @@
 <?php
 
-$request = \Config\Services::request();
+$request = service('request');

user_guide_src/source/incoming/incomingrequest/003.php

@@ -14,4 +14,4 @@ public function __construct(RequestInterface $request)
     }
 }
 
-$someClass = new SomeClass(\Config\Services::request());
+$someClass = new SomeClass(service('request'));

user_guide_src/source/libraries/caching.rst

@@ -19,7 +19,7 @@ The following example shows a common usage pattern within your controllers.
 
 .. literalinclude:: caching/001.php
 
-You can grab an instance of the cache engine directly through the Services class:
+You can grab an instance of the cache engine directly through the global function ``service()``:
 
 .. literalinclude:: caching/002.php
 

user_guide_src/source/libraries/caching/002.php

@@ -1,5 +1,5 @@
 <?php
 
-$cache = \Config\Services::cache();
+$cache = service('cache');
 
 $foo = $cache->get('foo');

user_guide_src/source/libraries/cookies/002.php

@@ -4,7 +4,7 @@
 use Config\Cookie as CookieConfig;
 
 // pass in a Config\Cookie instance before constructing a Cookie class
-Cookie::setDefaults(new CookieConfig());
+Cookie::setDefaults(config(CookieConfig::class));
 $cookie = new Cookie('login_token');
 
 // pass in an array of defaults

user_guide_src/source/libraries/cookies/003.php

@@ -3,7 +3,7 @@
 use CodeIgniter\Cookie\Cookie;
 use Config\Cookie as CookieConfig;
 
-$oldDefaults = Cookie::setDefaults(new CookieConfig());
+$oldDefaults = Cookie::setDefaults(config(CookieConfig::class));
 $cookie      = new Cookie('my_token', 'muffins');
 
 // return the old defaults

user_guide_src/source/libraries/cookies/007.php

@@ -1,5 +1,3 @@
 <?php
 
-use Config\Services;
-
-$cookieStore = Services::response()->getCookieStore();
+$cookieStore = service('response')->getCookieStore();

user_guide_src/source/libraries/cookies/009.php

@@ -2,7 +2,6 @@
 
 use CodeIgniter\Cookie\Cookie;
 use CodeIgniter\Cookie\CookieStore;
-use Config\Services;
 
 // check if cookie is in the current cookie collection
 $store = new CookieStore([
@@ -13,7 +12,7 @@
 
 // check if cookie is in the current Response's cookie collection
 cookies()->has('login_token');
-Services::response()->hasCookie('remember_token');
+service('response')->hasCookie('remember_token');
 
 // using the cookie helper to check the current Response
 // not available to v4.1.1 and lower

user_guide_src/source/libraries/cookies/010.php

@@ -13,7 +13,7 @@
 
 // getting cookie in the current Response's cookie collection
 cookies()->get('login_token');
-Services::response()->getCookie('remember_token');
+service('response')->getCookie('remember_token');
 
 // using the cookie helper to get cookie from the Response's cookie collection
 helper('cookie');

user_guide_src/source/libraries/cookies/013.php

@@ -1,11 +1,9 @@
 <?php
 
-use Config\Services;
-
 cookies()->get(); // array of Cookie objects
 
 // alternatively, you can use the display method
 cookies()->display();
 
 // or even from the Response
-Services::response()->getCookies();
+service('response')->getCookies();

user_guide_src/source/libraries/cookies/014.php

@@ -2,7 +2,6 @@
 
 use CodeIgniter\Cookie\Cookie;
 use CodeIgniter\Cookie\CookieStore;
-use Config\Services;
 
 $store = new CookieStore([
     new Cookie('login_token'),

user_guide_src/source/libraries/cookies/015.php

@@ -1,9 +1,7 @@
 <?php
 
-use Config\Services;
-
-Services::response()->setCookie('admin_token', 'yes');
-Services::response()->deleteCookie('login_token');
+service('response')->setCookie('admin_token', 'yes');
+service('response')->deleteCookie('login_token');
 
 // using the cookie helper
 helper('cookie');

user_guide_src/source/libraries/cookies/017.php

@@ -1,9 +1,8 @@
 <?php
 
 use CodeIgniter\Cookie\Cookie;
-use Config\Services;
 
-$response = Services::response();
+$response = service('response');
 
 $cookie = new Cookie(
     'remember_token',

user_guide_src/source/libraries/curlrequest.rst

@@ -50,7 +50,7 @@ Loading the Library
 
 The library can be loaded either manually or through the :doc:`Services class </concepts/services>`.
 
-To load with the Services class call the ``curlrequest()`` method:
+To load with the Services class call the ``curlrequest()`` method or global function ``service()``:
 
 .. literalinclude:: curlrequest/002.php
 

user_guide_src/source/libraries/curlrequest/002.php

@@ -1,3 +1,6 @@
 <?php
 
+$client = service('curlrequest'); // Since v4.5.0, this code is recommended due to performance improvements
+
+// The code above is the same as the code below.
 $client = \Config\Services::curlrequest();

user_guide_src/source/libraries/curlrequest/003.php

@@ -4,4 +4,4 @@
     'baseURI' => 'http://example.com/api/v1/',
     'timeout' => 3,
 ];
-$client = \Config\Services::curlrequest($options);
+$client = service('curlrequest', $options);

user_guide_src/source/libraries/curlrequest/004.php

@@ -1,8 +1,10 @@
 <?php
 
+use Config\App;
+
 $client = new \CodeIgniter\HTTP\CURLRequest(
-    new \Config\App(),
+    config(App::class),
     new \CodeIgniter\HTTP\URI(),
-    new \CodeIgniter\HTTP\Response(new \Config\App()),
+    new \CodeIgniter\HTTP\Response(config(App::class)),
     $options
 );

user_guide_src/source/libraries/curlrequest/005.php

@@ -1,6 +1,6 @@
 <?php
 
-$client = \Config\Services::curlrequest();
+$client = service('curlrequest');
 
 $response = $client->request('GET', 'https://api.github.com/user', [
     'auth' => ['user', 'pass'],

user_guide_src/source/libraries/curlrequest/008.php

@@ -1,6 +1,6 @@
 <?php
 
-$client = \Config\Services::curlrequest([
+$client = service('curlrequest', [
     'baseURI' => 'https://example.com/api/v1/',
 ]);
 

user_guide_src/source/libraries/email/001.php

@@ -1,6 +1,6 @@
 <?php
 
-$email = \Config\Services::email();
+$email = service('email');
 
 $email->setFrom('[email protected]', 'Your Name');
 $email->setTo('[email protected]');

user_guide_src/source/libraries/encryption/001.php

@@ -1,3 +1,3 @@
 <?php
 
-$encrypter = \Config\Services::encrypter();
+$encrypter = service('encrypter');

user_guide_src/source/libraries/encryption/003.php

@@ -1,7 +1,9 @@
 <?php
 
-$config         = new \Config\Encryption();
+use Config\Encryption;
+
+$config         = config(Encryption::class);
 $config->key    = 'aBigsecret_ofAtleast32Characters';
 $config->driver = 'OpenSSL';
 
-$encrypter = \Config\Services::encrypter($config);
+$encrypter = service('encrypter', $config);

user_guide_src/source/libraries/encryption/013.php

@@ -1,7 +1,6 @@
 <?php
 
 use Config\Encryption;
-use Config\Services;
 
 $config         = new Encryption();
 $config->driver = 'OpenSSL';
@@ -15,4 +14,4 @@
 $config->encryptKeyInfo = 'encryption';
 $config->authKeyInfo    = 'authentication';
 
-$encrypter = Services::encrypter($config, false);
+$encrypter = service('encrypter', $config);

user_guide_src/source/libraries/images.rst

@@ -22,12 +22,12 @@ Initializing the Class
 **********************
 
 Like most other classes in CodeIgniter, the image class is initialized
-in your controller by calling the Services class:
+in your controller by calling the global function ``service()``:
 
 .. literalinclude:: images/001.php
 
-You can pass the alias for the image library you wish to use into the
-Service function:
+You can pass the alias for the image library you wish to use into the global
+function ``service()``:
 
 .. literalinclude:: images/002.php
 

user_guide_src/source/libraries/images/001.php

@@ -1,3 +1,3 @@
 <?php
 
-$image = \Config\Services::image();
+$image = service('image');

user_guide_src/source/libraries/images/002.php

@@ -1,3 +1,3 @@
 <?php
 
-$image = \Config\Services::image('imagick');
+$image = service('image', 'imagick');

user_guide_src/source/libraries/images/007.php

@@ -1,6 +1,6 @@
 <?php
 
-$image = \Config\Services::image();
+$image = service('image');
 
 try {
     $image->withFile('/path/to/image/mypic.jpg')

user_guide_src/source/libraries/images/008.php

@@ -1,14 +1,14 @@
 <?php
 
-$info = \Config\Services::image('imagick')
+$info = service('image', 'imagick')
     ->withFile('/path/to/image/mypic.jpg')
     ->getFile()
     ->getProperties(true);
 
 $xOffset = ($info['width'] / 2) - 25;
 $yOffset = ($info['height'] / 2) - 25;
 
-\Config\Services::image('imagick')
+service('image', 'imagick')
     ->withFile('/path/to/image/mypic.jpg')
     ->crop(50, 50, $xOffset, $yOffset)
     ->save('/path/to/new/image.jpg');

user_guide_src/source/libraries/images/009.php

@@ -1,6 +1,6 @@
 <?php
 
-\Config\Services::image()
+service('image')
     ->withFile('/path/to/image/mypic.jpg')
     ->convert(IMAGETYPE_PNG)
     ->save('/path/to/new/image.png');

user_guide_src/source/libraries/images/010.php

@@ -1,6 +1,6 @@
 <?php
 
-\Config\Services::image('imagick')
+service('image', 'imagick')
     ->withFile('/path/to/image/mypic.jpg')
     ->fit(100, 150, 'left')
     ->save('/path/to/new/image.jpg');