[Summary view] [Print] [Text view]

   1  # http_build_url() for PHP
   2  
   3  [![Tests](https://github.com/ozh/http_build_url/actions/workflows/test.yml/badge.svg)](https://github.com/ozh/http_build_url/actions/workflows/test.yml)
   4  
   5  An implementation of [`http_build_url()`](https://www.php.net/manual/en/function.http-build-url.php),
   6  the URL builder from the `pecl_http` extension, for environments where that
   7  extension isn't installed.
   8  
   9  ## About this fork
  10  
  11  The original package, [jakeasmith/http_build_url](https://github.com/jakeasmith/http_build_url),
  12  was abandoned in favor of the URI API built into PHP 8.5. That's good advice for new
  13  code, but plenty of existing projects still call `http_build_url()` and just need
  14  it to keep working on modern PHP. So this fork picks up maintenance:
  15  
  16  - published on Packagist as **`ozh/http_build_url`**
  17  - PHP 8.1+ only, typed signature, tested up to PHP 8.5
  18  - same behavior and same function name as the original, so switching is a one-line
  19    change in `composer.json`
  20  
  21  If you are starting fresh on PHP 8.5+, use [`Uri\Rfc3986\Uri`](https://www.php.net/manual/en/class.uri-rfc3986-uri.php)
  22  instead; see [Modern alternative](#modern-alternative) below.
  23  
  24  ## Install
  25  
  26  ```sh
  27  composer require ozh/http_build_url
  28  ```
  29  
  30  ## Usage
  31  
  32  ```php
  33  http_build_url(
  34      string|array $url,
  35      string|array|null $parts = [],
  36      int $flags = HTTP_URL_REPLACE,
  37      ?array &$new_url = null
  38  ): string
  39  ```
  40  
  41  `$url` and `$parts` are each either a URL string or an associative array in the
  42  shape `parse_url()` returns. The parts of `$parts` are merged into `$url`
  43  according to `$flags`. If `$new_url` is passed, it is filled with the parts of
  44  the resulting URL, as `parse_url()` would return them.
  45  
  46  ```php
  47  // Replace parts of a URL (the default)
  48  echo http_build_url('http://example.com/some/path?a=b', ['host' => 'example.org']);
  49  // http://example.org/some/path?a=b
  50  
  51  // Join a relative path, merge the query string, drop auth and fragment
  52  echo http_build_url(
  53      'http://[email protected]/pub/index.php?a=b#files',
  54      [
  55          'scheme' => 'ftp',
  56          'host'   => 'ftp.example.com',
  57          'path'   => 'files/current/',
  58          'query'  => 'a=c',
  59      ],
  60      HTTP_URL_STRIP_AUTH | HTTP_URL_JOIN_PATH | HTTP_URL_JOIN_QUERY | HTTP_URL_STRIP_FRAGMENT
  61  );
  62  // ftp://ftp.example.com/pub/files/current/?a=c
  63  
  64  // Get the composed parts back
  65  http_build_url('http://example.com/path?a=b', [], HTTP_URL_STRIP_QUERY, $parts);
  66  // $parts === ['scheme' => 'http', 'host' => 'example.com', 'path' => '/path']
  67  ```
  68  
  69  ### Flags
  70  
  71  | Constant                   | Effect                                                     |
  72  |----------------------------|------------------------------------------------------------|
  73  | `HTTP_URL_REPLACE`         | Replace every part given in `$parts` (default)              |
  74  | `HTTP_URL_JOIN_PATH`       | Join the path of `$parts` onto the path of `$url`           |
  75  | `HTTP_URL_JOIN_QUERY`      | Merge the query strings of `$url` and `$parts`              |
  76  | `HTTP_URL_STRIP_USER`      | Strip the user                                              |
  77  | `HTTP_URL_STRIP_PASS`      | Strip the password                                          |
  78  | `HTTP_URL_STRIP_AUTH`      | Strip user and password                                     |
  79  | `HTTP_URL_STRIP_PORT`      | Strip the port                                              |
  80  | `HTTP_URL_STRIP_PATH`      | Strip the path                                              |
  81  | `HTTP_URL_STRIP_QUERY`     | Strip the query string                                      |
  82  | `HTTP_URL_STRIP_FRAGMENT`  | Strip the fragment                                          |
  83  | `HTTP_URL_STRIP_ALL`       | Strip everything but scheme and host                        |
  84  
  85  Scheme and host given in `$parts` are always applied, regardless of flags. The
  86  constants are defined only if they don't already exist, and use the same values
  87  as `pecl_http`.
  88  
  89  ## Modern alternative
  90  
  91  On PHP 8.5+, the built-in URI API covers most of the same ground:
  92  
  93  ```php
  94  use Uri\Rfc3986\Uri;
  95  
  96  echo Uri::parse('https://example.com/search?q=php#top')
  97      ->withPath('/docs')
  98      ->withQuery('page=2')
  99      ->withFragment(null)
 100      ->toString();
 101  // https://example.com/docs?page=2
 102  ```
 103  
 104  ## Tests
 105  
 106  ```sh
 107  composer install
 108  vendor/bin/phpunit
 109  ```
 110  
 111  ## License
 112  
 113  MIT, as the original. See [LICENSE](LICENSE).