From 226056eeac6567775a4204910c28f8ada2b0eda6 Mon Sep 17 00:00:00 2001
From: M Parker <mparker17@536298.no-reply.drupal.org>
Date: Mon, 2 Jun 2014 13:28:24 -0400
Subject: [PATCH] 2277623-4

---
 includes/common.inc | 58 ++++++++++++++++++++++++++++++-----------------------
 1 file changed, 33 insertions(+), 25 deletions(-)

diff --git a/includes/common.inc b/includes/common.inc
index e1a1673..006b106 100644
--- a/includes/common.inc
+++ b/includes/common.inc
@@ -544,37 +544,45 @@ function drupal_get_destination() {
 }
 
 /**
- * Parses a system URL string into an associative array suitable for url().
+ * Parses a URL string into it's path, query and fragment components.
  *
- * This function should only be used for URLs that have been generated by the
- * system, such as via url(). It should not be used for URLs that come from
- * external sources, or URLs that link to external resources.
+ * @link http://tools.ietf.org/html/rfc3986#section-3 RFC 3986 @endlink states
+ * that a URL consists of a scheme, authority, path, query and fragment. For
+ * example, in the URL
+ * @code foo://example.com:8042/over/there?name=ferret#nose @endcode, the scheme
+ * is @code foo @endcode, the authority is @code example.com:8042 @endcode, the
+ * path is @code over/there @endcode, the query is @code name=ferret @endcode
+ * and the fragment is @code nose @code.
  *
- * The returned array contains a 'path' that may be passed separately to url().
- * For example:
- * @code
- *   $options = drupal_parse_url($_GET['destination']);
+ * This function splits both internal paths like @code node?b=c#d @endcode and
+ * external URLs like @code https://example.com/a?b=c#d @endcode into their
+ * component parts.
+ *
+ * Note, however, that when passed an external URL, this function groups the
+ * scheme, authority and path together as $path.
+ *
+ * @param $url
+ *   The internal path or external URL to parse.
+ *
+ * @return array
+ *   An associative array containing:
+ *   - path: The path component of $url. If $url is an external URL, this
+ *     includes the scheme and host.
+ *   - 'query': An array of query parameters from $url, if they exist.
+ *   - 'fragment': The fragment component from $url, if it exists.
+ *   Note that the returned array contains a 'path' that must be passed
+ *   separately to url() and l(). For example:
+ *   @code
+ *   $options = UrlHelper::parse(\Drupal::request()->query->get('destination'));
  *   $my_url = url($options['path'], $options);
  *   $my_link = l('Example link', $options['path'], $options);
- * @endcode
+ *   @endcode
  *
- * This is required, because url() does not support relative URLs containing a
- * query string or fragment in its $path argument. Instead, any query string
- * needs to be parsed into an associative query parameter array in
- * $options['query'] and the fragment into $options['fragment'].
- *
- * @param $url
- *   The URL string to parse, f.e. $_GET['destination'].
- *
- * @return
- *   An associative array containing the keys:
- *   - 'path': The path of the URL. If the given $url is external, this includes
- *     the scheme and host.
- *   - 'query': An array of query parameters of $url, if existent.
- *   - 'fragment': The fragment of $url, if existent.
- *
- * @see url()
  * @see drupal_goto()
+ * @see l()
+ * @see url()
+ * @see http://tools.ietf.org/html/rfc3986
+ *
  * @ingroup php_wrappers
  */
 function drupal_parse_url($url) {
-- 
1.9.2