diff --git a/CHANGELOG.md b/CHANGELOG.md index 86ce915..b0d2d98 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,11 @@ # (MODX)EvolutionCMS.libraries.ddTools changelog +## Version 0.55 (2022-09-05) +* \+ `\ddTools::convertUrlToAbsolute`: The new public method. Converts relative URLs to absolute. See more info and examples in README.md. +* \* README: Various improvements. + + ## Version 0.54 (2022-01-08) * \+ `\DDTools\BaseClass::setExistingProps` → Parameters → `$props`: Can also be set as a [JSON](https://en.wikipedia.org/wiki/JSON), [HJSON](https://hjson.github.io/) or [Query formatted](https://en.wikipedia.org/wiki/Query_string) string. * \* Included PHP.libraries.HJSON has been updated from 2.1 to 2.2. diff --git a/CHANGELOG_ru.md b/CHANGELOG_ru.md index 999ad94..df14f65 100644 --- a/CHANGELOG_ru.md +++ b/CHANGELOG_ru.md @@ -1,6 +1,11 @@ # (MODX)EvolutionCMS.libraries.ddTools changelog +## Версия 0.55 (2022-09-05) +* \+ `\ddTools::convertUrlToAbsolute`: Новый публичный метод. Конвертирует относительные URL в абсолютные. См. больше информации и примеры в README. +* \* README: Различные улучшения. + + ## Версия 0.54 (2022-01-08) * \+ `\DDTools\BaseClass::setExistingProps` → Параметры → `$props`: Также может быть задан как строка в формете [JSON](https://ru.wikipedia.org/wiki/JSON), [HJSON](https://hjson.github.io/) или [Query](https://en.wikipedia.org/wiki/Query_string). * \* PHP.libraries.HJSON, включённая в репозиторий, обновлена с 2.1 до 2.2. diff --git a/README.md b/README.md index ddf86f5..d3ab8de 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ require_once( //Update (MODX)EvolutionCMS.libraries.ddTools \DDInstaller::install([ 'url' => 'https://github.com/DivanDesign/EvolutionCMS.libraries.ddTools', - 'type' => 'snippet' + 'type' => 'library' ]); ``` @@ -52,6 +52,48 @@ require_once( ## Parameters description +### `\ddTools::convertUrlToAbsolute($params)` + +Converts relative URLs to absolute. + +The method tends to change URL as little as possible and just prepends required scheme and/or host (or sometimes nothing at all). +All kinds of query parameters, hash, ports, etc. are not modified. + +* `$params` + * Desctription: Parameters, the pass-by-name style is used. + * Valid values: + * `stdClass` + * `arrayAssociative` + * **Required** + +* `$params->url` + * Desctription: Source URL. Can be set as: + * `'some/url'` — relative + * `'/some/url'` — relative starting with slash + * `'example.com/some/url'` — absolute starting with domain + * `'//example.com/some/url'` — absolute starting with double slash + * `'https://example.com/some/url'` — absolute starting with scheme + * Valid values: `string` + * **Required** + +* `$params->host` + * Desctription: Host for the result URL. + * Valid values: `string` + * Default value: `$_SERVER['HTTP_HOST']` + +* `$params->scheme` + * Desctription: Scheme for the result URL. + * Valid values: `string` + * Default value: `'https'` or `'http'` depending on `$_SERVER['HTTPS']` + + +#### Returns + +* `$result` + * Desctription: Source URL converted to absolute. Always contains scheme. + * Valid values: `string` + + ### `\ddTools::parseText($params)` Replaces placeholders in a text with required values. @@ -356,9 +398,9 @@ Arrays, [JSON](https://en.wikipedia.org/wiki/JSON) and [Query string](https://en * Desctription: Type of resulting object. Values are case insensitive (the following names are equal: `'stringjsonauto'`, `'stringJsonAuto'`, `'STRINGJSONAUTO'`, etc). * Valid values: - * `'objectAuto'` — `stdClass` or `array` depends on input string - * `'objectStdClass'` - * `'objectArray'` + * `'objectAuto'` — `stdClass` or `array` depends on input object + * `'objectStdClass'` — `stdClass` + * `'objectArray'` — `array` * `'stringJsonAuto'` — `stringJsonObject` or `stringJsonArray` depends on input object * `'stringJsonObject'` * `'stringJsonArray'` @@ -958,6 +1000,38 @@ Static method for easy running needed snippet using only it's name and parameter ## Examples +### `\ddTools::convertUrlToAbsolute($params)`: Convert relative URLs to absolute + +`$params->url` can be set in various ways for more convenience: + +```php +//Relative +$url = 'some/page?q=42#hash'; +//Relative starting with slash +$url = '/some/page?q=42#hash'; +//Absolute starting with domain +$url = 'example.com/some/page?q=42#hash'; +//Absolute starting with double slash +$url = '//example.com/some/page?q=42#hash'; +//Absolute starting with scheme +$url = 'https://example.com/some/page?q=42#hash'; +``` + +```php +\ddTools::convertUrlToAbsolute([ + 'url' => $url, + //The parameter is optional and is used here just for clarity. By default it will be equal to domain of your site. + 'host' => 'example.com' +]); +``` + +Returns this with any of the above URLs: + +```php +'https://example.com/some/page?q=42#hash' +``` + + ### Verify renamed snippet params (`\ddTools::verifyRenamedParams($params)`) Suppose we have the snippet `ddSendFeedback` with the `getEmail` and `getId` parameters. @@ -1008,10 +1082,13 @@ extract(\ddTools::verifyRenamedParams([ ``` -### `\DDTools\ObjectTools::convertType($params)` +### `\DDTools\ObjectTools` + + +#### `\DDTools\ObjectTools::convertType($params)` -#### Convert a JSON or Query encoded string to an array +##### Convert a JSON or Query encoded string to an array For example, some snippet supports 2 formats in one of parameters: JSON or Query string. Users use the format that is convenient to them and we support both. @@ -1044,7 +1121,7 @@ Both calls return: ``` -#### Convert a Query encoded string to a JSON object string +##### Convert a Query encoded string to a JSON object string ```php \DDTools\ObjectTools::convertType([ @@ -1063,7 +1140,7 @@ Returns: ``` -#### Convert a JSON object to a JSON array +##### Convert a JSON object to a JSON array ```php \DDTools\ObjectTools::convertType([ @@ -1085,7 +1162,7 @@ Returns: ``` -#### Convert a HJSON encoded string to an object +##### Convert a HJSON encoded string to an object ```php \DDTools\ObjectTools::convertType([ @@ -1115,10 +1192,10 @@ A simple syntax and easy to read.', ``` -### `\DDTools\ObjectTools::extend($params)` +#### `\DDTools\ObjectTools::extend($params)` -#### Merge two objects, modifying the first +##### Merge two objects, modifying the first ```php var_export(\DDTools\ObjectTools::extend([ @@ -1156,7 +1233,7 @@ stdClass::__set_state(array( ``` -#### Also you can extend arrays +##### Also you can extend arrays ```php var_export(\DDTools\ObjectTools::extend([ @@ -1194,7 +1271,7 @@ array( ``` -#### Moreover, objects can extend arrays and vice versa +##### Moreover, objects can extend arrays and vice versa ```php var_export(\DDTools\ObjectTools::extend([ @@ -1230,7 +1307,7 @@ array( ``` -#### Don't overwrite fields with empty values (`$params->overwriteWithEmpty` == `false`) +##### Don't overwrite fields with empty values (`$params->overwriteWithEmpty` == `false`) By default, empty field values (e. g. `''`) are treated as other values and will replace non-empty ones. @@ -1292,10 +1369,10 @@ stdClass::__set_state(array( ``` -### `\DDTools\ObjectTools::unfold($params)` +#### `\DDTools\ObjectTools::unfold($params)` -#### Unfold an object +##### Unfold an object ```php var_export(\DDTools\ObjectTools::unfold([ @@ -1324,7 +1401,7 @@ stdClass::__set_state(array ( ``` -#### Unfold an array +##### Unfold an array ```php var_export(\DDTools\ObjectTools::unfold([ @@ -1355,7 +1432,7 @@ array ( ``` -#### Use custom key separator +##### Use custom key separator ```php var_export(\DDTools\ObjectTools::unfold([ @@ -1381,6 +1458,68 @@ stdClass::__set_state(array ( ``` +#### `\DDTools\ObjectTools::isPropExists($params)` + +Checks if the object, class or array has a property / element using the same syntax. + +You can pass an object: + +```php +var_export(\DDTools\ObjectTools::isPropExists([ + 'object' => (object) [ + 'firstName' => 'John', + 'lastName' => 'Lennon' + ], + 'propName' => 'firstName' +])); +``` + +Or an array: + +```php +var_export(\DDTools\ObjectTools::isPropExists([ + 'object' => [ + 'firstName' => 'Paul', + 'lastName' => 'McCartney' + ], + 'propName' => 'firstName' +])); +``` + +Both calls return `true`. + + +#### `\DDTools\ObjectTools::getPropValue($params)` + +Get the value of an object property or an array element using the same syntax. + +You can pass an object: + +```php +var_export(\DDTools\ObjectTools::getPropValue([ + 'object' => (object) [ + 'name' => 'Floyd', + 'weight' => 7 + ], + 'propName' => 'name' +])); +``` + +Or an array: + +```php +var_export(\DDTools\ObjectTools::getPropValue([ + 'object' => [ + 'name' => 'Floyd', + 'weight' => 7 + ], + 'propName' => 'name' +])); +``` + +Both calls return `'Floyd'`. + + ### `\DDTools\ObjectCollection` @@ -1768,68 +1907,6 @@ array( ``` -### `\DDTools\ObjectTools::isPropExists($params)` - -Checks if the object, class or array has a property / element using the same syntax. - -You can pass an object: - -```php -var_export(\DDTools\ObjectTools::isPropExists([ - 'object' => (object) [ - 'firstName' => 'John', - 'lastName' => 'Lennon' - ], - 'propName' => 'firstName' -])); -``` - -Or an array: - -```php -var_export(\DDTools\ObjectTools::isPropExists([ - 'object' => [ - 'firstName' => 'Paul', - 'lastName' => 'McCartney' - ], - 'propName' => 'firstName' -])); -``` - -Both calls return `true`. - - -### `\DDTools\ObjectTools::getPropValue($params)` - -Get the value of an object property or an array element using the same syntax. - -You can pass an object: - -```php -var_export(\DDTools\ObjectTools::getPropValue([ - 'object' => (object) [ - 'name' => 'Floyd', - 'weight' => 7 - ], - 'propName' => 'name' -])); -``` - -Or an array: - -```php -var_export(\DDTools\ObjectTools::getPropValue([ - 'object' => [ - 'name' => 'Floyd', - 'weight' => 7 - ], - 'propName' => 'name' -])); -``` - -Both calls return `'Floyd'`. - - ## Links * [Home page](https://code.divandesign.biz/modx/ddtools) diff --git a/composer.json b/composer.json index 5aaaede..b98ebe3 100644 --- a/composer.json +++ b/composer.json @@ -1,7 +1,7 @@ { "name": "dd/evolutioncms-libraries-ddtools", "type": "modxevo-library-ddtools", - "version": "0.54.0", + "version": "0.55.0", "description": "A library with various tools facilitating your work.", "keywords": [ "modx", diff --git a/modx.ddtools.class.php b/modx.ddtools.class.php index 89f6ef0..36351ea 100644 --- a/modx.ddtools.class.php +++ b/modx.ddtools.class.php @@ -1,7 +1,7 @@ url {string} — Source URL. Can be set as relative with(out) host or absolute with(out) protocol: example.com/some/url, some/url, /some/url, //example.com/some/url, https://example.com/some/url. @required + * @param $params->host {string} — Host for the result URL. Default: $_SERVER['HTTP_HOST']. + * @param $params->scheme {string} — Scheme for the result URL. Default: 'https' || 'http' depending on $_SERVER['HTTPS']. + * + * @return {string} + */ + public static function convertUrlToAbsolute($params){ + //# Prepare params + $params = \DDTools\ObjectTools::extend([ + 'objects' => [ + //Defaults + (object) [ + 'url' => '', + 'host' => $_SERVER['HTTP_HOST'], + 'scheme' => null + ], + $params + ] + ]); + + if (is_null($params->scheme)){ + $params->scheme = + ( + isset($_SERVER['HTTPS']) && + ( + $_SERVER['HTTPS'] == 'on' || + $_SERVER['HTTPS'] == 1 + ) + ) ? + 'https' : + 'http' + ; + } + + + //# Run + $result = ''; + + //E. g. '//example.com/some/url' + if ( + substr( + $params->url, + 0, + 2 + ) == + '//' + ){ + $result = + $params->scheme . + ':' . + $params->url + ; + //E. g. 'https://example.com/some/url' + }elseif ( + !empty(parse_url( + $params->url, + PHP_URL_SCHEME + )) + ){ + $result = $params->url; + //E. g. 'example.com/some/url' + }elseif ( + strpos( + $params->url, + $params->host + ) === + 0 + ){ + $result = + $params->scheme . + '://' . + $params->url + ; + //E. g. 'some/url', '/some/url' + }else{ + $result = + $params->scheme . + '://' . + $params->host . + '/' . + ltrim( + $params->url, + '/' + ) + ; + } + + return $result; + } + /** * generateRandomString * @version 1.0.3 (2018-06-17)