Commit inicial powerservice

This commit is contained in:
Gabriel
2026-10-19 12:45:45 -06:00
commit ad85486fe2
10158 changed files with 2736804 additions and 0 deletions
@@ -0,0 +1,630 @@
<?php
namespace WordPress\DataLiberation\BlockMarkup;
use WP_Error;
use WP_HTML_Tag_Processor;
/**
* A processor class capable of reading and rewriting block markup.
*
* This class provides functionality to parse, traverse and modify WordPress block markup.
* It extends WP_HTML_Tag_Processor to add block-specific capabilities like:
* - Parsing block comments into name and attributes
* - Tracking block nesting depth
* - Modifying block attributes
* - Validating block structure
*
* Contrary to WP_HTML_Tag_Processor, this class does not support streaming.
* It assumes block markup blobs are small enough to fit into memory, otherwise
* WordPress won't be able to render them anyway.
*
* @see WP_HTML_Tag_Processor
*/
class BlockMarkupProcessor extends WP_HTML_Tag_Processor {
/**
* The name of the current block (e.g. 'core/paragraph')
*
* @var string|null
*/
private $block_name;
/**
* The attributes of the current block as an associative array
*
* @var array<string, mixed>|null
*/
protected $block_attributes;
/**
* Whether the current block's attributes have been modified and need to be serialized
*
* @var bool
*/
private $block_attributes_updated;
/**
* Whether the current block token is a closing tag (e.g. <!-- /wp:paragraph -->)
*
* @var bool
*/
private $block_closer;
/**
* Whether the current block is self-closing (e.g. <!-- wp:spacer /-->)
*
* @var bool
*/
private $self_closing_flag;
/**
* Stack tracking the names of currently open blocks for validation
*
* @var array<string>
*/
private $stack_of_open_blocks = array();
/**
* The most recent error encountered while parsing blocks
*
* @var string|null
*/
private $last_block_error;
/**
* A flattened list of paths (arrays of keys) to every attribute found in
* $block_attributes. This is used by next_block_attribute() to traverse
* attributes without relying on PHP iterator classes.
*
* @var array<int, array<int|string>>|null
*/
private $block_attribute_paths = null;
/**
* The index of the current attribute inside $block_attribute_paths.
* Starts at -1 so that the first call to next_block_attribute() positions
* the cursor at index 0.
*
* @var int
*/
private $block_attribute_index = -1;
/**
* Gets the type of the current token, adding a special '#block-comment' type
* for WordPress block delimiters.
*
* @return string|null The token type or null if no token
*/
public function get_token_type(): ?string {
switch ( $this->parser_state ) {
case self::STATE_COMMENT:
if ( null !== $this->block_name ) {
return '#block-comment';
}
return '#comment';
default:
return parent::get_token_type();
}
}
/**
* Gets the most recent error encountered while parsing blocks
*
* @return WP_Error|null The error message or null if no error
*/
public function get_last_error(): ?WP_Error {
return $this->last_block_error;
}
/**
* Advances past the block closer of the currently matched block and returns
* the HTML content found between the block's opener and closer.
*
* @return string|false The inner HTML content of the block or false if not a block opener.
*/
public function skip_and_get_block_inner_html() {
if ( '#block-comment' !== $this->get_token_type() ) {
return false;
}
if ( $this->is_block_closer() ) {
return false;
}
if ( false === WP_HTML_Tag_Processor::set_bookmark( 'block-start' ) ) {
return false;
}
$starting_block_depth = $this->get_block_depth();
while ( $this->next_token() ) {
if (
'#block-comment' === $this->get_token_type() &&
$this->is_block_closer() &&
$this->get_block_depth() === $starting_block_depth - 1
) {
break;
}
}
if ( false === WP_HTML_Tag_Processor::set_bookmark( 'block-end' ) ) {
WP_HTML_Tag_Processor::release_bookmark( 'block-start' );
return false;
}
$inner_html_start = $this->bookmarks['block-start']->start + $this->bookmarks['block-start']->length;
$inner_html_end = $this->bookmarks['block-end']->start - $inner_html_start;
WP_HTML_Tag_Processor::release_bookmark( 'block-start' );
WP_HTML_Tag_Processor::release_bookmark( 'block-end' );
return substr(
$this->html,
$inner_html_start,
$inner_html_end
);
}
/**
* Gets the depth of the currently matched block on the block stack. It only
* considers the parent blocks and not HTML elements.
*
* For example, the paragraph block in the following markup has a depth of 1:
*
* <!-- wp:core/blockquote -->
* <blockquote>
* <!-- wp:core/paragraph -->
* <p>Hello, there</p>
* <!-- /wp:core/paragraph -->
* </blockquote>
* <!-- /wp:core/blockquote -->
*
* @return int The number of ancestor blocks
*/
public function get_block_depth() {
return count( $this->stack_of_open_blocks );
}
/**
* Gets the names of all currently open blocks from outermost to innermost
*
* @return array List of block names in nesting order
*/
public function get_block_breadcrumbs() {
return $this->stack_of_open_blocks;
}
/**
* Returns the name of the block if the current token is a block comment.
*
* @return string|false The block name (e.g. 'core/paragraph') or false if not at a block
*/
public function get_block_name() {
if ( null === $this->block_name ) {
return false;
}
return $this->block_name;
}
/**
* Gets all attributes of the current block
*
* @return array|false The block attributes or false if not at a block
*/
public function get_block_attributes() {
if ( null === $this->block_attributes ) {
return false;
}
return $this->block_attributes;
}
/**
* Gets a specific attribute value from the current block
*
* @param string $attribute_name The name of the attribute to get
*
* @return mixed|false The attribute value or false if not found
*/
public function get_block_attribute( $attribute_name ) {
if ( null === $this->block_attributes ) {
return false;
}
return $this->block_attributes[ $attribute_name ] ?? false;
}
/**
* Overwrites all the block attributes of the currently matched block
* opener.
*
* @param array $attributes The new attributes to set
*
* @return bool Whether the attributes were successfully set
*/
public function set_block_attributes( $attributes ) {
if ( '#block-comment' !== $this->get_token_type() ) {
return false;
}
if ( $this->is_block_closer() ) {
return false;
}
$this->block_attributes = $attributes;
$this->block_attributes_updated = true;
return true;
}
/**
* Checks if the currently matched token is a block closer,
* e.g. <!-- /wp:paragraph -->.
*
* @return bool True if at a block closer.
*/
public function is_block_closer() {
return null !== $this->block_name && true === $this->block_closer;
}
/**
* Checks if the currently matched token is a self-closing block,
* e.g. <!-- wp:spacer /-->.
*
* @return bool True if at a self-closing block.
*/
public function is_self_closing_block() {
return null !== $this->block_name && true === $this->self_closing_flag;
}
/**
* Advances to the next token in the HTML stream. Matches:
* - The regular HTML tokens
* - WordPress block openers
* - WordPress block closers
* - WordPress self-closing blocks
*
* @return bool Whether a token was parsed.
*/
public function next_token(): bool {
if ( $this->has_bookmark( 'block-delimiter' ) ) {
$this->release_bookmark( 'block-delimiter' );
}
$this->get_updated_html();
$this->block_name = null;
$this->block_attributes = null;
$this->block_attribute_paths = null;
$this->block_attribute_index = -1;
$this->block_closer = false;
$this->self_closing_flag = false;
$this->block_attributes_updated = false;
while ( true ) {
if ( false === parent::next_token() ) {
return false;
}
if (
'#tag' === $this->get_token_type() && (
'HTML' === $this->get_tag() ||
'HEAD' === $this->get_tag() ||
'BODY' === $this->get_tag()
)
) {
continue;
}
break;
}
if ( '#comment' !== parent::get_token_type() ) {
return true;
}
$text = parent::get_modifiable_text();
/**
* Try to parse as a block. The block parser won't cut it because
* while it can parse blocks, it has no semantics for rewriting the
* block markup. Let's do our best here:
*/
$at = strspn( $text, " \t\f\r\n" ); // Whitespace.
if ( $at >= strlen( $text ) ) {
// This is an empty comment. Not a block.
return true;
}
// Blocks closers start with the solidus character (`/`).
if ( '/' === $text[ $at ] ) {
$this->block_closer = true;
++$at;
}
// Blocks start with wp.
if ( ! (
$at + 3 < strlen( $text ) &&
'w' === $text[ $at ] &&
'p' === $text[ $at + 1 ] &&
':' === $text[ $at + 2 ]
) ) {
return true;
}
$name_starts_at = $at;
// Skip wp.
$at += 3;
// Parse the actual block name after wp.
$name_length = strspn( $text, 'abcdefghijklmnopqrstuwxvyzABCDEFGHIJKLMNOPRQSTUWXVYZ0123456789_-', $at );
if ( 0 === $name_length ) {
// This wasn't a block after all, just a regular comment.
$this->last_block_error = new WP_Error(
'suspicious-delimiter',
sprintf( 'An HTML comment started with "wp:" that was not followed by a valid block name: %s', $text )
);
return true;
}
$name = substr( $text, $name_starts_at, $name_length + 3 );
$at += $name_length;
// Assume no attributes by default.
$attributes = array();
// Skip the whitespace that follows the block name.
$at += strspn( $text, " \t\f\r\n", $at );
if ( $at < strlen( $text ) ) {
// It may be a self-closing block or a block with attributes.
// However, block closers can be neither – let's short-circuit.
if ( $this->block_closer ) {
return true;
}
// The rest of the comment can only consist of block attributes
// and an optional solidus character.
$rest = ltrim( substr( $text, $at ) );
$at = strlen( $text );
// Inspect our potential JSON for the self-closing solidus (`/`) character.
$json_maybe = $rest;
if ( '/' === substr( $json_maybe, - 1 ) ) {
// Self-closing block (<!-- wp:image /-->).
$this->self_closing_flag = true;
$json_maybe = substr( $json_maybe, 0, - 1 );
}
// Let's try to parse attributes as JSON.
if ( strlen( $json_maybe ) > 0 ) {
$attributes = json_decode( trim( $json_maybe ), true );
if ( null === $attributes || ! is_array( $attributes ) ) {
// This comment looked like a block comment, but the attributes didn't
// parse as a JSON array. This means it wasn't a block after all.
$this->last_block_error = new WP_Error(
'suspicious-delimiter',
sprintf( '%s could be parsed as a delimiter but JSON attributes were malformed: %s.', $name, $json_maybe )
);
return true;
}
}
}
// We have a block name and a valid attributes array. We may not find a block
// closer, but let's assume is a block and process it as such
// @TODO: Confirm that WordPress block parser would have parsed this as a block.
$this->block_name = $name;
$this->block_attributes = $attributes;
if ( $this->block_closer ) {
$popped = array_pop( $this->stack_of_open_blocks );
if ( $popped !== $name ) {
$this->last_block_error = new WP_Error(
'mismatched-closer',
sprintf( 'Block closer %s does not match the last opened block %s.', $name, $popped )
);
return false;
}
} elseif ( ! $this->self_closing_flag ) {
array_push( $this->stack_of_open_blocks, $name );
}
$this->set_bookmark( 'block-delimiter' );
return true;
}
public function get_block_delimiter_span() {
if ( ! $this->has_bookmark( 'block-delimiter' ) ) {
return false;
}
return $this->bookmarks['block-delimiter'];
}
public function next_block_delimiter() {
while ( $this->next_token() ) {
if ( '#block-comment' === $this->get_token_type() ) {
break;
}
}
if ( '#block-comment' !== $this->get_token_type() ) {
return false;
}
return true;
}
/**
* @inheritDoc
*/
public function get_updated_html(): string {
$this->block_attribute_updates_to_modifiable_text_updates();
return parent::get_updated_html();
}
/**
* Converts block attribute updates into lexical updates.
*
* @return bool Whether any lexical updates were created
*/
private function block_attribute_updates_to_modifiable_text_updates() {
// Apply block attribute updates, if any.
if ( ! $this->block_attributes_updated ) {
return false;
}
$encoded_attributes = json_encode(
$this->block_attributes,
JSON_HEX_TAG | // Convert < and > to \u003C and \u003E.
JSON_HEX_AMP // Convert & to \u0026.
);
if ( '[]' === $encoded_attributes ) {
$encoded_attributes = '';
} else {
$encoded_attributes .= ' ';
}
$this->set_modifiable_text(
' ' .
$this->block_name .
' ' .
$encoded_attributes .
( $this->is_self_closing_block() ? '/' : '' )
);
return true;
}
/**
* Advances to the next block attribute when a block is matched.
*
* @return bool Whether we successfully advanced to the next attribute.
*/
public function next_block_attribute() {
if ( '#block-comment' !== $this->get_token_type() ) {
return false;
}
if ( null === $this->block_attribute_paths ) {
$block_attributes = $this->get_block_attributes();
if ( ! is_array( $block_attributes ) ) {
return false;
}
$this->block_attribute_paths = $this->build_block_attribute_paths( $block_attributes );
$this->block_attribute_index = -1;
}
++$this->block_attribute_index;
return isset( $this->block_attribute_paths[ $this->block_attribute_index ] );
}
protected function get_block_attribute_path() {
if ( null === $this->block_attribute_paths || ! isset( $this->block_attribute_paths[ $this->block_attribute_index ] ) ) {
return false;
}
return $this->block_attribute_paths[ $this->block_attribute_index ];
}
/**
* Gets the key of the currently matched block attribute.
*
* @return string|false The attribute key or false if no attribute was matched
*/
public function get_block_attribute_key() {
if ( null === $this->block_attribute_paths || ! isset( $this->block_attribute_paths[ $this->block_attribute_index ] ) ) {
return false;
}
$path = $this->block_attribute_paths[ $this->block_attribute_index ];
return $path[ count( $path ) - 1 ];
}
/**
* Gets the value of the currently matched block attribute.
*
* @return mixed|false The attribute value or false if no attribute was matched
*/
public function get_block_attribute_value() {
if ( null === $this->block_attribute_paths || ! isset( $this->block_attribute_paths[ $this->block_attribute_index ] ) ) {
return false;
}
$path = $this->block_attribute_paths[ $this->block_attribute_index ];
$value = $this->block_attributes;
foreach ( $path as $segment ) {
if ( ! is_array( $value ) || ! array_key_exists( $segment, $value ) ) {
return false;
}
$value = $value[ $segment ];
}
return $value;
}
/**
* Sets the value of the currently matched block attribute.
*
* @param mixed $new_value The new value to set
*
* @return bool Whether the value was successfully set
*/
public function set_block_attribute_value( $new_value ) {
if ( null === $this->block_attribute_paths || ! isset( $this->block_attribute_paths[ $this->block_attribute_index ] ) ) {
return false;
}
$path = $this->block_attribute_paths[ $this->block_attribute_index ];
$ref =& $this->block_attributes;
$depth = count( $path );
for ( $i = 0; $i < $depth - 1; $i++ ) {
$segment = $path[ $i ];
if ( ! is_array( $ref ) || ! array_key_exists( $segment, $ref ) ) {
return false; // Path is invalid.
}
$ref =& $ref[ $segment ];
}
$last_key = $path[ $depth - 1 ];
$ref[ $last_key ] = $new_value;
$this->block_attributes_updated = true;
return true;
}
/**
* Builds a list of attribute paths, using a depth-first, SELF_FIRST order
* that matches the previous iterator behaviour.
*
* @param array<int|string, mixed> $attributes
* @param array<int|string> $base_path
* @return array<int, array<int|string>>
*/
private function build_block_attribute_paths( $attributes, $base_path = array() ) {
$paths = array();
foreach ( $attributes as $key => $value ) {
$current_path = array_merge( $base_path, array( $key ) );
$paths[] = $current_path; // SELF_FIRST: include parent before children.
if ( is_array( $value ) ) {
$paths = array_merge( $paths, $this->build_block_attribute_paths( $value, $current_path ) );
}
}
return $paths;
}
}
@@ -0,0 +1,542 @@
<?php
namespace WordPress\DataLiberation\BlockMarkup;
use VendorPrefix\Rowbot\URL\URL;
use WordPress\DataLiberation\URL\URLInTextProcessor;
use WordPress\DataLiberation\URL\CSSURLProcessor;
use WordPress\DataLiberation\URL\WPURL;
/**
* Reports all the URLs in the imported post and enables rewriting them.
*/
class BlockMarkupUrlProcessor extends BlockMarkupProcessor {
private $raw_url;
/**
* @var URL
*/
private $parsed_url;
private $base_url_string;
private $base_url_object;
private $url_in_text_processor;
private $url_in_text_node_updated;
private $css_url_processor;
private $css_url_processor_updated;
/**
* The list of names of URL-related HTML attributes that may be available on
* the current token. They will be inspected by next_url_attribute().
*
* Possible values:
*
* - null: We haven't inspected any attribute yet.
* - array: The first element is the currently inspected attribute
* and the rest of the list are elements yet to be inspected on
* the upcoming next_url_attribute() call.
* - empty array: We've already inspected all the URL-related attributes.
*
* @var array<string>|null
*/
private $inspecting_html_attributes;
public function __construct( $html, ?string $base_url_string = null ) {
parent::__construct( $html );
$this->base_url_string = $base_url_string;
$this->base_url_object = $base_url_string ? WPURL::parse( $base_url_string ) : null;
}
public function get_updated_html(): string {
if ( $this->url_in_text_node_updated ) {
$this->set_modifiable_text( $this->url_in_text_processor->get_updated_text() );
$this->url_in_text_node_updated = false;
}
if ( $this->css_url_processor_updated ) {
if ( null !== $this->css_url_processor ) {
$updated_css = $this->css_url_processor->get_updated_css();
$this->set_attribute( 'style', $updated_css );
}
$this->css_url_processor_updated = false;
}
return parent::get_updated_html();
}
public function get_raw_url() {
return $this->raw_url;
}
public function get_parsed_url() {
return $this->parsed_url;
}
public function next_token(): bool {
$this->get_updated_html();
$this->raw_url = null;
$this->parsed_url = null;
$this->inspecting_html_attributes = null;
$this->url_in_text_processor = null;
$this->css_url_processor = null;
/*
* Do not reset url_in_text_node_updated or css_url_processor_updated – they're reset
* in get_updated_html() which is called in parent::next_token().
*/
return parent::next_token();
}
public function next_url() {
do {
if ( $this->next_url_in_current_token() ) {
return true;
}
} while ( false !== $this->next_token() );
return false;
}
public function next_url_in_current_token() {
$this->raw_url = null;
switch ( parent::get_token_type() ) {
case '#tag':
return $this->next_url_attribute();
case '#block-comment':
return $this->next_url_block_attribute();
case '#text':
return $this->next_url_in_text_node();
default:
return false;
}
}
private function next_url_in_text_node() {
if ( '#text' !== $this->get_token_type() ) {
return false;
}
if ( null === $this->url_in_text_processor ) {
/*
* Use the base URL for URLs matched in text nodes. This is the only
* way to recognize a substring "WordPress.org" as a URL. We might
* get some false positives this way, e.g. in this string:
*
* > And that's how you build a theme. Now let's take a look at..."
*
* `theme.Now` would be recognized as a URL. It's up to the API consumer
* to filter out such false positives e.g. by checking the domain against
* a list of accepted domains, or the TLD against a list of public suffixes.
*/
$this->url_in_text_processor = new URLInTextProcessor( $this->get_modifiable_text(), $this->base_url_string );
}
while ( $this->url_in_text_processor->next_url() ) {
$this->raw_url = $this->url_in_text_processor->get_raw_url();
$this->parsed_url = $this->url_in_text_processor->get_parsed_url();
return true;
}
return false;
}
/**
* Advances to the next CSS URL in the `style` attribute of the current tag token.
*
* @return bool Whether a CSS URL was found.
*/
private function next_url_in_css() {
if ( '#tag' !== $this->get_token_type() ) {
return false;
}
if ( null === $this->css_url_processor ) {
$css_value = $this->get_attribute( 'style' );
if ( ! is_string( $css_value ) ) {
return false;
}
$this->css_url_processor = new CSSURLProcessor( $css_value );
}
while ( $this->css_url_processor->next_url() ) {
/**
* Skip data URIs. They may be really large and they don't
* have a hostname to migrate.
*/
if ( $this->css_url_processor->is_data_uri() ) {
continue;
}
$this->raw_url = $this->css_url_processor->get_raw_url();
$this->parsed_url = WPURL::parse( $this->raw_url, $this->base_url_string );
if ( false === $this->parsed_url ) {
continue;
}
return true;
}
return false;
}
private function next_url_attribute() {
$tag = $this->get_tag();
// Check if we have a style attribute with CSS URLs to process.
if ( null !== $this->css_url_processor ) {
if ( $this->next_url_in_css() ) {
return true;
}
// Done with CSS URLs in this attribute, apply any pending updates and move on.
$this->get_updated_html();
$this->css_url_processor = null;
}
if ( null === $this->inspecting_html_attributes ) {
if ( array_key_exists( $tag, self::HTML_ATTRIBUTES_TO_ACCEPT_RELATIVE_URLS_FROM ) ) {
/**
* Initialize the list on the first call to next_url_attribute()
* for the current token. The last element is the attribute we'll
* inspect in the while() loop below.
*/
$this->inspecting_html_attributes = self::HTML_ATTRIBUTES_TO_ACCEPT_RELATIVE_URLS_FROM[ $tag ];
// Add style attribute to the list if it exists.
if ( null !== $this->get_attribute( 'style' ) ) {
$this->inspecting_html_attributes[] = 'style';
}
} elseif ( null !== $this->get_attribute( 'style' ) ) {
$this->inspecting_html_attributes = array( 'style' );
} else {
return false;
}
} else {
/**
* Forget the attribute we've inspected on the previous call to
* next_url_attribute().
*/
array_pop( $this->inspecting_html_attributes );
}
while ( count( $this->inspecting_html_attributes ) > 0 ) {
$attr = $this->inspecting_html_attributes[ count( $this->inspecting_html_attributes ) - 1 ];
$url_maybe = $this->get_attribute( $attr );
if ( ! is_string( $url_maybe ) ) {
array_pop( $this->inspecting_html_attributes );
continue;
}
// Rewrite any CSS `url()` declarations in the `style` attribute.
if ( 'style' === $attr ) {
$this->css_url_processor = new CSSURLProcessor( $url_maybe );
if ( $this->next_url_in_css() ) {
return true;
}
// No CSS URLs found, move to next attribute.
$this->css_url_processor = null;
array_pop( $this->inspecting_html_attributes );
continue;
}
/*
* Use base URL to resolve known URI attributes as we are certain we're
* dealing with URI values.
* With a base URL, the string "plugins.php" in <a href="plugins.php"> will
* be correctly recognized as a URL.
* Without a base URL, this Processor would incorrectly skip it.
*/
$parsed_url = WPURL::parse( $url_maybe, $this->base_url_string );
if ( false === $parsed_url ) {
array_pop( $this->inspecting_html_attributes );
continue;
}
$this->raw_url = $url_maybe;
$this->parsed_url = $parsed_url;
return true;
}
return false;
}
private function next_url_block_attribute() {
while ( $this->next_block_attribute() ) {
$url_maybe = $this->get_block_attribute_value();
if ( ! is_string( $url_maybe ) ||
count( $this->get_block_attribute_path() ) > 1
) {
// @TODO: support arrays, objects, and other non-string data structures.
continue;
}
/**
* Decide whether the current block attribute holds a URL.
*
* Known URL attributes can be assumed to hold a URL and be
* parsed with the base URL. For example, a "/about-us" value
* in a wp:navigation-link block's `url` attribute is a
* relative URL to the `/about-us` page.
*
* Other attributes may or may not contain URLs, but we cannot assume
* they do. A value `/about-us` could be a relative URL or a class name.
* In those cases, we'll let go of relative URLs and only detect
* absolute URLs to avoid treating every string as a URL. This requires
* parsing without a base URL.
*/
$is_relative_url_block_attribute = (
isset( self::BLOCK_ATTRIBUTES_TO_ACCEPT_RELATIVE_URLS_FROM[ $this->get_block_name() ] ) &&
in_array( $this->get_block_attribute_key(), self::BLOCK_ATTRIBUTES_TO_ACCEPT_RELATIVE_URLS_FROM[ $this->get_block_name() ], true )
);
/**
* Filters whether a block attribute is known to contain a relative URL.
*
* This filter allows extending the list of block attributes that are
* recognized as containing URLs. When a block attribute is marked as
* a known URL attribute, it will be parsed with the base URL, allowing
* relative URLs to be properly resolved.
*
* @since 6.8.0
*
* @param bool $is_relative_url_block_attribute Whether the block attribute is known to contain a relative URL.
* @param array $context {
* Context information about the block attribute.
*
* @type string $block_name The name of the block (e.g., 'wp:image', 'wp:button').
* @type string $attribute_name The name of the attribute (e.g., 'url', 'href').
* }
*/
$is_relative_url_block_attribute = apply_filters(
'url_processor_is_relative_url_block_attribute',
$is_relative_url_block_attribute,
array(
'block_name' => $this->get_block_name(),
'attribute_name' => $this->get_block_attribute_key(),
)
);
$parsed_url = false;
if ( $is_relative_url_block_attribute ) {
// Known relative URL attribute – let's parse with the base URL.
$parsed_url = WPURL::parse( $url_maybe, $this->base_url_string );
} else {
// Other attributes – let's parse without a base URL (and only detect absolute URLs).
$parsed_url = WPURL::parse( $url_maybe );
}
if ( false === $parsed_url ) {
continue;
}
$this->raw_url = $url_maybe;
$this->parsed_url = $parsed_url;
return true;
}
return false;
}
/**
* Replaces the currently matched URL with a new one.
*
* @param string $raw_url The raw URL.
* @param URL $parsed_url The parsed version of the raw URL. It is required
* as $raw_url might be a relative URL pointing to a different
* host than this processor's base URL.
*
* @return bool True if the URL was set, false otherwise.
*/
public function set_url( $raw_url, $parsed_url ) {
if ( null === $this->raw_url ) {
return false;
}
$this->raw_url = $raw_url;
$this->parsed_url = $parsed_url;
switch ( parent::get_token_type() ) {
case '#tag':
// Check if we're processing a CSS URL.
if ( null !== $this->css_url_processor ) {
$this->css_url_processor_updated = true;
return $this->css_url_processor->set_raw_url( $raw_url );
}
$attr = $this->get_inspected_attribute_name();
if ( false === $attr ) {
return false;
}
$this->set_attribute( $attr, $raw_url );
return true;
case '#block-comment':
return $this->set_block_attribute_value( $raw_url );
case '#text':
if ( null === $this->url_in_text_processor ) {
return false;
}
$this->url_in_text_node_updated = true;
return $this->url_in_text_processor->set_raw_url( $raw_url );
}
}
/**
* Rewrites the components of the currently matched URL from ones
* provided in $from_url to ones specified in $to_url.
*
* It preserves the relative nature of the matched URL.
*
* @TODO: Should this method live in this class? It's specific to the import process
* and the URL rewriting logic and has knowledge about the quirks of detecting
* relative URLs in text nodes. On the other hand, the detection is performed
* by this WPURL_In_Text_Processor class so maybe the two do go hand in hand?
*/
public function replace_base_url( URL $to_url, ?URL $base_url = null ) {
$base_url = $base_url ?? $this->base_url_object;
if ( ! $base_url ) {
return false;
}
$result = WPURL::replace_base_url(
$this->get_parsed_url(),
array(
'old_base_url' => $base_url,
'new_base_url' => $to_url,
'raw_url' => $this->get_raw_url(),
'is_relative' => (
/**
* In text nodes, the only detected URLs are absolute. The tricky part
* is they may start without a protocol, e.g. `wordpress.org`. Therefore,
* we need to tell WPURL::replace_base_url what's our intention regarding
* the URL's relativity. It cannot just infer it from the URL itself.
*/
'#text' !== $this->get_token_type() &&
! WPURL::can_parse( $this->get_raw_url() )
),
)
);
if ( false === $result ) {
return false;
}
$this->set_url( $result . '', $result->new_url );
return true;
}
/**
* Returns true if the currently matched URL is absolute.
*
* @return bool Whether the currently matched URL is absolute.
*/
public function is_url_absolute() {
return WPURL::can_parse( $this->get_raw_url() );
}
public function get_inspected_attribute_name() {
if ( '#tag' !== $this->get_token_type() ) {
return false;
}
if ( null === $this->inspecting_html_attributes ) {
return false;
}
if ( empty( $this->inspecting_html_attributes ) ) {
return false;
}
return $this->inspecting_html_attributes[ count( $this->inspecting_html_attributes ) - 1 ];
}
/**
* A list of block attributes that are known to contain URLs.
*
* It covers WordPress core blocks as of WordPress version 6.9. It can be
* extended by plugins and themes via the "url_processor_is_relative_url_block_attribute"
* filter.
*
* @var array
*/
public const BLOCK_ATTRIBUTES_TO_ACCEPT_RELATIVE_URLS_FROM = array(
'wp:button' => array( 'url', 'linkTarget' ),
'wp:cover' => array( 'url' ),
'wp:embed' => array( 'url' ),
'wp:gallery' => array( 'url', 'fullUrl' ),
'wp:image' => array( 'url', 'src', 'href' ),
'wp:media-text' => array( 'mediaUrl', 'href' ),
'wp:navigation-link' => array( 'url' ),
'wp:navigation-submenu' => array( 'url' ),
'wp:rss' => array( 'feedURL' ),
);
/**
* A list of HTML attributes meant to contain URLs, as defined in the HTML specification.
* It includes some deprecated attributes like `lowsrc` and `highsrc` for the `IMG` element.
*
* See https://html.spec.whatwg.org/multipage/indices.html#attributes-1.
* See https://stackoverflow.com/questions/2725156/complete-list-of-html-tag-attributes-which-have-a-url-value.
*/
public const HTML_ATTRIBUTES_TO_ACCEPT_RELATIVE_URLS_FROM = array(
'A' => array( 'href' ),
'APPLET' => array( 'codebase', 'archive' ),
'AREA' => array( 'href' ),
'AUDIO' => array( 'src' ),
'BASE' => array( 'href' ),
'BLOCKQUOTE' => array( 'cite' ),
'BODY' => array( 'background' ),
'BUTTON' => array( 'formaction' ),
'COMMAND' => array( 'icon' ),
'DEL' => array( 'cite' ),
'EMBED' => array( 'src' ),
'FORM' => array( 'action' ),
'FRAME' => array( 'longdesc', 'src' ),
'HEAD' => array( 'profile' ),
'HTML' => array( 'manifest' ),
'IFRAME' => array( 'longdesc', 'src' ),
// SVG <image> element.
'IMAGE' => array( 'href' ),
'IMG' => array( 'longdesc', 'src', 'usemap', 'lowsrc', 'highsrc' ),
'INPUT' => array( 'src', 'usemap', 'formaction' ),
'INS' => array( 'cite' ),
'LINK' => array( 'href' ),
'OBJECT' => array( 'classid', 'codebase', 'data', 'usemap' ),
'Q' => array( 'cite' ),
'SCRIPT' => array( 'src' ),
'SOURCE' => array( 'src' ),
'TRACK' => array( 'src' ),
'VIDEO' => array( 'poster', 'src' ),
);
/**
* @TODO: Either explicitly support these attributes, or explicitly drop support for
* handling their subsyntax. A generic URL matcher might be good enough.
*/
public const HTML_ATTRIBUTES_WITH_SUBSYNTAX_TO_ACCEPT_RELATIVE_URLS_FROM = array(
'*' => array( 'style' ), // background(), background-image().
'APPLET' => array( 'archive' ),
'IMG' => array( 'srcset' ),
'META' => array( 'content' ),
'SOURCE' => array( 'srcset' ),
'OBJECT' => array( 'archive' ),
);
/**
* Also <style> and <script> tag content can contain URLs.
* <style> has specific syntax rules we can use for matching, but perhaps a generic matcher would be good enough?
*
* <style>
* #domID { background:url(https://mysite.com/wp-content/uploads/image.png) }
* </style>
*
* @TODO: Either explicitly support these tags, or explicitly drop support for
* handling their subsyntax. A generic URL matcher might be good enough.
*/
public const HTML_TAGS_WITH_SUBSYNTAX_TO_ACCEPT_RELATIVE_URLS_FROM = array(
'STYLE',
'SCRIPT',
);
}
@@ -0,0 +1,15 @@
<?php
namespace WordPress\DataLiberation\BlockMarkup;
class BlockObject {
public $block_name;
public $attrs;
public $inner_blocks;
public function __construct( $block_name, $attrs = array(), $inner_blocks = array() ) {
$this->block_name = $block_name;
$this->attrs = $attrs;
$this->inner_blocks = $inner_blocks;
}
}
@@ -0,0 +1,973 @@
<?php
namespace WordPress\DataLiberation\EntityReader;
use WordPress\ByteStream\ReadStream\ByteReadStream;
use WordPress\DataLiberation\ImportEntity;
use WordPress\XML\XMLProcessor;
use WordPress\XML\XMLUnsupportedException;
/**
* Data Liberation API: WP_WXR_Entity_Reader class
*
* Reads WordPress eXtended RSS (WXR) files and emits entities like posts,
* comments, users, and terms. Enables efficient processing of large WXR
* files without loading everything into memory.
*
* Note this is just a reader. It doesn't import any data into WordPress. It
* only reads meaningful entities from the WXR file.
*
* ## Design goals
*
* WP_WXR_Entity_Reader is built with the following characteristics in mind:
*
* * Speed – it should be as fast as possible
* * No PHP extensions required – it can run on any PHP installation
* * Reliability – no random crashes when encountering malformed XML or UTF-8 sequences
* * Low, predictable memory footprint to support 1000GB+ WXR files
* * Ability to pause, finish execution, and resume later, e.g. after a fatal error
*
* ## Implementation
*
* `WP_WXR_Entity_Reader` uses the `WP_XML_Processor` to find XML tags representing meaningful
* WordPress entities. The reader knows the WXR schema and only looks for relevant elements.
* For example, it knows that posts are stored in `rss > channel > item` and comments are
* stored in `rss > channel > item > `wp:comment`.
*
* The `$wxr->next_entity()` method stream-parses the next entity from the WXR document and
* exposes it to the API consumer via `$wxr->get_entity_type()` and `$wxr->get_entity_date()`.
* The next call to `$wxr->next_entity()` remembers where the parsing has stopped and parses
* the next entity after that point.
*
* Example:
*
* $reader = WP_WXR_Entity_Reader::create_for_streaming();
*
* // Add data as it becomes available
* $reader->append_bytes( fread( $file_handle, 65536 ) );
*
* // Process entities
* while ( $reader->next_entity() ) {
* switch ( $wxr_reader->get_entity_type() ) {
* case 'post':
* // ... process post ...
* break;
*
* case 'comment':
* // ... process comment ...
* break;
*
* case 'site_option':
* // ... process site option ...
* break;
*
* // ... process other entity types ...
* }
* }
*
* // Check if we need more input
* if ( $reader->is_paused_at_incomplete_input() ) {
* // Add more data and continue processing
* $reader->append_bytes( fread( $file_handle, 65536 ) );
* }
*
* The next_entity() -> fread -> break usage pattern may seem a bit tedious. This is expected. Even
* if the WXR parsing part of the WP_WXR_Entity_Reader offers a high-level API, working with byte streams
* requires reasoning on a much lower level. The StreamChain class shipped in this repository will
* make the API consumption easier with its transformation–oriented API for chaining data processors.
*
* Similarly to `WP_XML_Processor`, the `WP_WXR_Entity_Reader` enters a paused state when it doesn't
* have enough XML bytes to parse the entire entity.
*
* ## Caveats
*
* ### Extensibility
*
* `WP_WXR_Entity_Reader` ignores any XML elements it doesn't recognize. The WXR format is extensible
* so in the future the reader may start supporting registration of custom handlers for unknown
* tags in the future.
*
* ### Nested entities intertwined with data
*
* `WP_WXR_Entity_Reader` flushes the current entity whenever another entity starts. The upside is
* simplicity and a tiny memory footprint. The downside is that it's possible to craft a WXR
* document where some information would be lost. For example:
*
* ```xml
* <rss>
* <channel>
* <item>
* <title>Page with comments</title>
* <link>http://wpthemetestdata.wordpress.com/about/page-with-comments/</link>
* <wp:postmeta>
* <wp:meta_key>_wp_page_template</wp:meta_key>
* <wp:meta_value><![CDATA[default]]></wp:meta_value>
* </wp:postmeta>
* <wp:post_id>146</wp:post_id>
* </item>
* </channel>
* </rss>
* ```
*
* `WP_WXR_Entity_Reader` would accumulate post data until the `wp:post_meta` tag. Then it would emit a
* `post` entity and accumulate the meta information until the `</wp:postmeta>` closer. Then it
* would advance to `<wp:post_id>` and **ignore it**.
*
* This is not a problem in all the `.wxr` files I saw. Still, it is important to note this limitation.
* It is possible there is a `.wxr` generator somewhere out there that intertwines post fields with post
* meta and comments. If this ever comes up, we could:
*
* * Emit the `post` entity first, then all the nested entities, and then emit a special `post_update` entity.
* * Do multiple passes over the WXR file – one for each level of nesting, e.g. 1. Insert posts, 2. Insert Comments, 3. Insert comment meta
*
* Buffering all the post meta and comments seems like a bad idea – there might be gigabytes of data.
*
* ## Remaining work
*
* @TODO:
*
* - Revisit the need to implement the Iterator interface.
*
* @since WP_VERSION
*/
class WXREntityReader implements EntityReader {
/**
* The XML processor used to parse the WXR file.
*
* @since WP_VERSION
* @var WP_XML_Processor
*/
private $xml;
/**
* The name of the XML tag containing information about the WordPress entity
* currently being extracted from the WXR file.
*
* @since WP_VERSION
* @var string|null
*/
private $entity_tag;
/**
* The name of the current WordPress entity, such as 'post' or 'comment'.
*
* @since WP_VERSION
* @var string|null
*/
private $entity_type;
/**
* The data accumulated for the current entity.
*
* @since WP_VERSION
* @var array
*/
private $entity_data;
/**
* The byte offset of the current entity in the original input stream.
*
* @since WP_VERSION
* @var int
*/
private $entity_opener_byte_offset;
/**
* Whether the current entity has been emitted.
*
* @since WP_VERSION
* @var bool
*/
private $entity_finished = false;
/**
* The number of entities read so far.
*
* @since WP_VERSION
* @var int
*/
private $entities_read_so_far = 0;
/**
* The attributes from the last opening tag.
*
* @since WP_VERSION
* @var array
*/
private $last_opener_attributes = array();
/**
* The ID of the last processed post.
*
* @since WP_VERSION
* @var int|null
*/
private $last_post_id = null;
/**
* The ID of the last processed comment.
*
* @since WP_VERSION
* @var int|null
*/
private $last_comment_id = null;
/**
* Buffer for accumulating text content between tags.
*
* @since WP_VERSION
* @var string
*/
private $text_buffer = '';
/**
* Stream to pull bytes from when the input bytes are exhausted.
*
* @var WP_Byte_Producer
*/
private $upstream;
/**
* Whether the reader has finished processing the input stream.
*
* @var bool
*/
private $is_finished = false;
/**
* Mapping of WXR tags representing site options to their WordPress options names.
* These tags are only matched if they are children of the <channel> element.
*
* @since WP_VERSION
* @var array
*/
private $known_site_options = array();
/**
* Mapping of WXR tags to their corresponding entity types and field mappings.
*
* @since WP_VERSION
* @var array
*/
private $known_entities = array();
public static function create( ?ByteReadStream $upstream = null, $cursor = null, $options = array() ) {
$xml_cursor = null;
if ( null !== $cursor ) {
$cursor = json_decode( $cursor, true );
if ( false === $cursor ) {
_doing_it_wrong(
__METHOD__,
'Invalid cursor provided for WP_WXR_Entity_Reader::create().',
null
);
return false;
}
$xml_cursor = $cursor['xml'];
}
$xml = XMLProcessor::create_for_streaming( '', $xml_cursor );
$reader = new WXREntityReader( $xml, $options );
if ( null !== $cursor ) {
$reader->last_post_id = $cursor['last_post_id'];
$reader->last_comment_id = $cursor['last_comment_id'];
}
if ( null !== $upstream ) {
$reader->connect_upstream( $upstream );
if ( null !== $cursor ) {
if ( ! isset( $cursor['upstream'] ) ) {
// No upstream cursor means we've processed the
// entire input stream.
$xml->input_finished();
$xml->next_token();
} else {
$upstream->seek( $cursor['upstream'] );
}
}
}
return $reader;
}
/**
* Constructor.
*
* @param XMLProcessor $xml The XML processor to use.
*
* @since WP_VERSION
*/
protected function __construct( XMLProcessor $xml, $options = array() ) {
$this->xml = $xml;
if ( isset( $options['known_site_options'] ) || isset( $options['known_entities'] ) ) {
$this->known_site_options = isset( $options['known_site_options'] ) ? $options['known_site_options'] : array();
$this->known_entities = isset( $options['known_entities'] ) ? $options['known_entities'] : array();
return;
}
// Every XML element is a combination of a long-form namespace and a
// local element name, e.g. a syntax <wp:post_id> could actually refer
// to a (https://wordpress.org/export/1.0/, post_id) element.
//
// Namespaces are paramount for parsing XML and cannot be ignored. Elements
// element must be matched based on both their namespace and local name.
//
// Unfortunately, different WXR files defined the `wp` namespace in a different way.
// Folks use a mixture of HTTP vs HTTPS protocols and version numbers. We must
// account for all possible options to parse these documents correctly.
$wxr_namespaces = array(
'http://wordpress.org/export/1.0/',
'https://wordpress.org/export/1.0/',
'http://wordpress.org/export/1.1/',
'https://wordpress.org/export/1.1/',
'http://wordpress.org/export/1.2/',
'https://wordpress.org/export/1.2/',
);
$this->known_entities = array(
'item' => array(
'type' => 'post',
'fields' => array(
'title' => 'post_title',
'link' => 'link',
'guid' => 'guid',
'description' => 'post_excerpt',
'pubDate' => 'post_published_at',
'{http://purl.org/dc/elements/1.1/}creator' => 'post_author',
'{http://purl.org/rss/1.0/modules/content/}encoded' => 'post_content',
'{http://wordpress.org/export/1.0/excerpt/}encoded' => 'post_excerpt',
'{http://wordpress.org/export/1.1/excerpt/}encoded' => 'post_excerpt',
'{http://wordpress.org/export/1.2/excerpt/}encoded' => 'post_excerpt',
),
),
);
foreach ( $wxr_namespaces as $wxr_namespace ) {
$this->known_site_options = array_merge(
$this->known_site_options,
array(
'{' . $wxr_namespace . '}base_blog_url' => 'home',
'{' . $wxr_namespace . '}base_site_url' => 'siteurl',
'title' => 'blogname',
)
);
$this->known_entities['item']['fields'] = array_merge(
$this->known_entities['item']['fields'],
array(
'{' . $wxr_namespace . '}post_id' => 'post_id',
'{' . $wxr_namespace . '}status' => 'post_status',
'{' . $wxr_namespace . '}post_date' => 'post_date',
'{' . $wxr_namespace . '}post_date_gmt' => 'post_date_gmt',
'{' . $wxr_namespace . '}post_modified' => 'post_modified',
'{' . $wxr_namespace . '}post_modified_gmt' => 'post_modified_gmt',
'{' . $wxr_namespace . '}comment_status' => 'comment_status',
'{' . $wxr_namespace . '}ping_status' => 'ping_status',
'{' . $wxr_namespace . '}post_name' => 'post_name',
'{' . $wxr_namespace . '}post_parent' => 'post_parent',
'{' . $wxr_namespace . '}menu_order' => 'menu_order',
'{' . $wxr_namespace . '}post_type' => 'post_type',
'{' . $wxr_namespace . '}post_password' => 'post_password',
'{' . $wxr_namespace . '}is_sticky' => 'is_sticky',
'{' . $wxr_namespace . '}attachment_url' => 'attachment_url',
)
);
$this->known_entities = array_merge(
$this->known_entities,
array(
'{' . $wxr_namespace . '}comment' => array(
'type' => 'comment',
'fields' => array(
'{' . $wxr_namespace . '}comment_id' => 'comment_id',
'{' . $wxr_namespace . '}comment_author' => 'comment_author',
'{' . $wxr_namespace . '}comment_author_email' => 'comment_author_email',
'{' . $wxr_namespace . '}comment_author_url' => 'comment_author_url',
'{' . $wxr_namespace . '}comment_author_IP' => 'comment_author_IP',
'{' . $wxr_namespace . '}comment_date' => 'comment_date',
'{' . $wxr_namespace . '}comment_date_gmt' => 'comment_date_gmt',
'{' . $wxr_namespace . '}comment_content' => 'comment_content',
'{' . $wxr_namespace . '}comment_approved' => 'comment_approved',
'{' . $wxr_namespace . '}comment_type' => 'comment_type',
'{' . $wxr_namespace . '}comment_parent' => 'comment_parent',
'{' . $wxr_namespace . '}comment_user_id' => 'comment_user_id',
),
),
'{' . $wxr_namespace . '}commentmeta' => array(
'type' => 'comment_meta',
'fields' => array(
'{' . $wxr_namespace . '}meta_key' => 'meta_key',
'{' . $wxr_namespace . '}meta_value' => 'meta_value',
),
),
'{' . $wxr_namespace . '}author' => array(
'type' => 'user',
'fields' => array(
'{' . $wxr_namespace . '}author_id' => 'ID',
'{' . $wxr_namespace . '}author_login' => 'user_login',
'{' . $wxr_namespace . '}author_email' => 'user_email',
'{' . $wxr_namespace . '}author_display_name' => 'display_name',
'{' . $wxr_namespace . '}author_first_name' => 'first_name',
'{' . $wxr_namespace . '}author_last_name' => 'last_name',
),
),
'{' . $wxr_namespace . '}postmeta' => array(
'type' => 'post_meta',
'fields' => array(
'{' . $wxr_namespace . '}meta_key' => 'meta_key',
'{' . $wxr_namespace . '}meta_value' => 'meta_value',
),
),
'{' . $wxr_namespace . '}term' => array(
'type' => 'term',
'fields' => array(
'{' . $wxr_namespace . '}term_id' => 'term_id',
'{' . $wxr_namespace . '}term_taxonomy' => 'taxonomy',
'{' . $wxr_namespace . '}term_slug' => 'slug',
'{' . $wxr_namespace . '}term_parent' => 'parent',
'{' . $wxr_namespace . '}term_name' => 'name',
),
),
'{' . $wxr_namespace . '}tag' => array(
'type' => 'tag',
'fields' => array(
'{' . $wxr_namespace . '}term_id' => 'term_id',
'{' . $wxr_namespace . '}tag_slug' => 'slug',
'{' . $wxr_namespace . '}tag_name' => 'name',
'{' . $wxr_namespace . '}tag_description' => 'description',
),
),
'{' . $wxr_namespace . '}category' => array(
'type' => 'category',
'fields' => array(
'{' . $wxr_namespace . '}category_nicename' => 'slug',
'{' . $wxr_namespace . '}category_parent' => 'parent',
'{' . $wxr_namespace . '}cat_name' => 'name',
'{' . $wxr_namespace . '}category_description' => 'description',
),
),
)
);
}
}
public function get_reentrancy_cursor() {
/**
* @TODO: Instead of adjusting the XML cursor internals, adjust the get_reentrancy_cursor()
* call to support $bookmark_name, e.g. $this->xml->get_reentrancy_cursor( 'last_entity' );
* If the cursor internal data was a part of every bookmark, this would have worked
* even after evicting the actual bytes where $last_entity is stored.
*/
$xml_cursor = $this->xml->get_reentrancy_cursor();
$xml_cursor = json_decode( base64_decode( $xml_cursor ), true ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_decode
$xml_cursor['upstream_bytes_forgotten'] = $this->entity_opener_byte_offset;
$xml_cursor = base64_encode( json_encode( $xml_cursor ) ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_encode
return json_encode(
array(
'xml' => $xml_cursor,
'upstream' => $this->entity_opener_byte_offset,
'last_post_id' => $this->last_post_id,
'last_comment_id' => $this->last_comment_id,
)
);
}
/**
* Gets the data for the current entity.
*
* @return ImportEntity The entity.
* @since WP_VERSION
*/
public function get_entity() {
if ( ! $this->get_entity_type() ) {
return false;
}
return new ImportEntity(
$this->get_entity_type(),
$this->entity_data
);
}
/**
* Gets the type of the current entity.
*
* @return string|false The entity type, or false if no entity is being processed.
* @since WP_VERSION
*/
private function get_entity_type() {
if ( null !== $this->entity_type ) {
return $this->entity_type;
}
if ( null === $this->entity_tag ) {
return false;
}
if ( ! array_key_exists( $this->entity_tag, $this->known_entities ) ) {
return false;
}
return $this->known_entities[ $this->entity_tag ]['type'];
}
/**
* Gets the ID of the last processed post.
*
* @return int|null The post ID, or null if no posts have been processed.
* @since WP_VERSION
*/
public function get_last_post_id() {
return $this->last_post_id;
}
/**
* Gets the ID of the last processed comment.
*
* @return int|null The comment ID, or null if no comments have been processed.
* @since WP_VERSION
*/
public function get_last_comment_id() {
return $this->last_comment_id;
}
/**
* Appends bytes to the input stream.
*
* @param string $bytes The bytes to append.
*
* @since WP_VERSION
*/
public function append_bytes( string $bytes ): void {
$this->xml->append_bytes( $bytes );
}
/**
* Marks the input as finished.
*
* @since WP_VERSION
*/
public function input_finished(): void {
$this->xml->input_finished();
}
/**
* Checks if processing is finished.
*
* @return bool Whether processing is finished.
* @since WP_VERSION
*/
public function is_finished(): bool {
return $this->is_finished;
}
/**
* Checks if processing is paused waiting for more input.
*
* @return bool Whether processing is paused.
* @since WP_VERSION
*/
public function is_paused_at_incomplete_input(): bool {
return $this->xml->is_paused_at_incomplete_input();
}
/**
* Gets the last error that occurred.
*
* @return string|null The error message, or null if no error occurred.
* @since WP_VERSION
*/
public function get_last_error(): ?string {
return $this->xml->get_last_error();
}
public function get_xml_exception(): ?XMLUnsupportedException {
return $this->xml->get_exception();
}
/**
* Advances to the next entity in the WXR file.
*
* @return bool Whether another entity was found.
* @since WP_VERSION
*/
public function next_entity() {
if ( $this->is_finished ) {
return false;
}
while ( true ) {
if ( $this->read_next_entity() ) {
return true;
}
// If the read failed because of incomplete input data,
// try pulling more bytes from upstream before giving up.
if ( $this->is_paused_at_incomplete_input() ) {
if ( $this->pull_upstream_bytes() ) {
continue;
} else {
break;
}
}
$this->is_finished = true;
break;
}
return false;
}
/**
* Advances to the next entity in the WXR file.
*
* @return bool Whether another entity was found.
* @since WP_VERSION
*/
private function read_next_entity() {
if ( $this->xml->is_finished() ) {
$this->after_entity();
return false;
}
if ( $this->xml->is_paused_at_incomplete_input() ) {
return false;
}
/**
* This is the first call after emitting an entity.
* Remove the previous entity details from the internal state
* and prepare for the next entity.
*/
if ( $this->entity_type && $this->entity_finished ) {
$this->after_entity();
// If we finished processing the entity on a closing tag, advance the XML processor to.
// the next token. Otherwise the array_key_exists( $tag, static::known_entities ) branch.
// below will cause an infinite loop.
if ( $this->xml->is_tag_closer() ) {
if ( false === $this->xml->next_token() ) {
return false;
}
}
}
/**
* Main parsing loop. It advances the XML parser state until a full entity
* is available.
*/
do {
$breadcrumbs = $this->xml->get_breadcrumbs();
// Don't process anything outside the <rss> <channel> hierarchy.
if (
count( $breadcrumbs ) < 2 ||
array( '', 'rss' ) !== $breadcrumbs[0] ||
array( '', 'channel' ) !== $breadcrumbs[1]
) {
continue;
}
/*
* Buffer text and CDATA sections until we find the next tag.
* Each tag may contain multiple text or CDATA sections so we can't
* just assume that a single `get_modifiable_text()` call would get
* the entire text content of an element.
*/
if (
'#text' === $this->xml->get_token_type() ||
'#cdata-section' === $this->xml->get_token_type()
) {
$this->text_buffer .= $this->xml->get_modifiable_text();
continue;
}
// We're only interested in tags after this point.
if ( '#tag' !== $this->xml->get_token_type() ) {
continue;
}
if ( count( $breadcrumbs ) <= 2 && $this->xml->is_tag_opener() ) {
$this->entity_opener_byte_offset = $this->xml->get_token_byte_offset_in_the_input_stream();
}
$tag_with_namespace = $this->xml->get_tag_namespace_and_local_name();
/**
* Custom adjustment: the Accessibility WXR file uses a non-standard
* wp:wp_author tag.
*
* @TODO: Should WP_WXR_Entity_Reader care about such non-standard tags when
* the regular WXR importer would ignore them? Perhaps a warning
* and an upstream PR would be a better solution.
*/
if ( '{http://wordpress.org/export/1.2/}wp_author' === $tag_with_namespace ) {
$tag_with_namespace = '{http://wordpress.org/export/1.2/}author';
}
/**
* If the tag is a known entity root, assume the previous entity is
* finished, emit it, and start processing the new entity the next
* time this function is called.
*/
if ( array_key_exists( $tag_with_namespace, $this->known_entities ) ) {
if ( $this->entity_type && ! $this->entity_finished ) {
$this->emit_entity();
return true;
}
$this->after_entity();
// Only tag openers indicate a new entity. Closers just mean
// the previous entity is finished.
if ( $this->xml->is_tag_opener() ) {
$this->set_entity_tag( $tag_with_namespace );
$this->entity_opener_byte_offset = $this->xml->get_token_byte_offset_in_the_input_stream();
}
continue;
}
/**
* We're inside of an entity tag at this point.
*
* The following code assumes that we'll only see three types of tags:
*
* * Empty elements – such as <wp:comment_content />, that we'll ignore
* * XML element openers with only text nodes inside them.
* * XML element closers.
*
* Specifically, we don't expect to see any nested XML elements such as:
*
* <wp:comment_content>
* <title>Pygmalion</title>
* Long time ago...
* </wp:comment_content>
*
* The semantics of such a structure is not clear. The WP_WXR_Entity_Reader will
* enter an error state when it encounters such a structure.
*
* Such nesting wasn't found in any WXR files analyzed when building
* this class. If it actually is a part of the WXR standard, every
* supported nested element will need a custom handler.
*/
/**
* Buffer the XML tag opener attributes for later use.
*
* In WXR files, entity attributes come from two sources:
* * XML attributes on the tag itself
* * Text content between the opening and closing tags
*
* We store the XML attributes when encountering an opening tag,
* but wait until the closing tag to process the entity attributes.
* Why? Because only at that point we have both the attributes
* and all the related text nodes.
*/
if ( $this->xml->is_tag_opener() ) {
$this->last_opener_attributes = array();
// Get non-namespaced attributes.
$names = $this->xml->get_attribute_names_with_prefix( '', '' );
foreach ( $names as list($namespace, $name) ) {
$this->last_opener_attributes[ $name ] = $this->xml->get_attribute( $namespace, $name );
}
$this->text_buffer = '';
$is_site_option_opener = (
3 === count( $this->xml->get_breadcrumbs() ) &&
$this->xml->matches_breadcrumbs( array( 'rss', 'channel', '*' ) ) &&
array_key_exists( $this->xml->get_tag_namespace_and_local_name(), $this->known_site_options )
);
if ( $is_site_option_opener ) {
$this->entity_opener_byte_offset = $this->xml->get_token_byte_offset_in_the_input_stream();
}
continue;
}
/**
* At this point we're looking for the nearest tag closer so we can
* turn the buffered data into an entity attribute.
*/
if ( ! $this->xml->is_tag_closer() ) {
continue;
}
if (
! $this->entity_finished &&
array( array( '', 'rss' ), array( '', 'channel' ) ) === $this->xml->get_breadcrumbs()
) {
// Look for site options in children of the <channel> tag.
if ( $this->parse_site_option() ) {
return true;
} else {
// Keep looking for an entity if none was found in the current tag.
continue;
}
}
/**
* Special handling to accumulate categories stored inside the <category>
* tag found inside <item> tags.
*
* For example, we want to convert this:
*
* <category><![CDATA[Uncategorized]]></category>
* <category domain="category" nicename="wordpress">
* <![CDATA[WordPress]]>
* </category>
*
* Into this:
*
* 'terms' => [
* [ 'taxonomy' => 'category', 'slug' => '', 'description' => 'Uncategorized' ],
* [ 'taxonomy' => 'category', 'slug' => 'WordPress', 'description' => 'WordPress' ],
* ]
*/
if (
'post' === $this->entity_type &&
'category' === $this->xml->get_tag_local_name() &&
array_key_exists( 'domain', $this->last_opener_attributes ) &&
array_key_exists( 'nicename', $this->last_opener_attributes )
) {
$this->entity_data['terms'][] = array(
'taxonomy' => $this->last_opener_attributes['domain'],
'slug' => $this->last_opener_attributes['nicename'],
'description' => $this->text_buffer,
);
$this->text_buffer = '';
continue;
}
/**
* Store the text content of known tags as the value of the corresponding
* entity attribute as defined by the $known_entities mapping.
*
* Ignores tags unlisted in the $known_entities mapping.
*
* The WXR format is extensible so this reader could potentially
* support registering custom handlers for unknown tags in the future.
*/
if ( ! isset( $this->known_entities[ $this->entity_tag ]['fields'][ $tag_with_namespace ] ) ) {
continue;
}
$key = $this->known_entities[ $this->entity_tag ]['fields'][ $tag_with_namespace ];
$this->entity_data[ $key ] = $this->text_buffer;
$this->text_buffer = '';
} while ( $this->xml->next_token() );
if ( $this->is_paused_at_incomplete_input() ) {
return false;
}
/**
* Emit the last unemitted entity after parsing all the data.
*/
if (
$this->is_finished() &&
$this->entity_type &&
! $this->entity_finished
) {
$this->emit_entity();
return true;
}
return false;
}
/**
* Emits a site option entity from known children of the <channel>
* tag, e.g. <wp:base_blog_url> or <title>.
*
* @return bool Whether a site_option entity was emitted.
*/
private function parse_site_option() {
if ( ! array_key_exists( $this->xml->get_tag_namespace_and_local_name(), $this->known_site_options ) ) {
return false;
}
$this->entity_type = 'site_option';
$this->entity_data = array(
'option_name' => $this->known_site_options[ $this->xml->get_tag_namespace_and_local_name() ],
'option_value' => $this->text_buffer,
);
$this->emit_entity();
return true;
}
/**
* Connects a byte stream to automatically pull bytes from once
* the last input chunk have been processed.
*
* @param ByteReadStream $stream The upstream stream.
*/
public function connect_upstream( ByteReadStream $stream ) {
$this->upstream = $stream;
}
/**
* Appends another chunk of bytes from upstream if available.
*/
private function pull_upstream_bytes() {
if ( ! $this->upstream ) {
return false;
}
if ( $this->upstream->reached_end_of_data() ) {
$this->input_finished();
return false;
}
$available_bytes = $this->upstream->pull( 65536 );
$this->append_bytes( $this->upstream->consume( $available_bytes ) );
return true;
}
/**
* Marks the current entity as emitted and updates tracking variables.
*
* @since WP_VERSION
*/
private function emit_entity() {
if ( 'post' === $this->entity_type ) {
// Not all posts have a `<wp:post_id>` tag.
$this->last_post_id = isset( $this->entity_data['post_id'] ) ? $this->entity_data['post_id'] : null;
} elseif ( 'post_meta' === $this->entity_type ) {
$this->entity_data['post_id'] = $this->last_post_id;
} elseif ( 'comment' === $this->entity_type ) {
$this->last_comment_id = $this->entity_data['comment_id'];
$this->entity_data['post_id'] = $this->last_post_id;
} elseif ( 'comment_meta' === $this->entity_type ) {
$this->entity_data['comment_id'] = $this->last_comment_id;
} elseif ( 'tag' === $this->entity_type ) {
$this->entity_data['taxonomy'] = 'post_tag';
} elseif ( 'category' === $this->entity_type ) {
$this->entity_data['taxonomy'] = 'category';
}
$this->entity_finished = true;
++$this->entities_read_so_far;
}
/**
* Sets the current entity tag and type.
*
* @param string $tag_with_namespace The entity tag name.
*
* @since WP_VERSION
*/
private function set_entity_tag( string $tag_with_namespace ) {
$this->entity_tag = $tag_with_namespace;
if ( array_key_exists( $tag_with_namespace, $this->known_entities ) ) {
$this->entity_type = $this->known_entities[ $tag_with_namespace ]['type'];
}
}
/**
* Resets the state after processing an entity.
*
* @since WP_VERSION
*/
private function after_entity() {
$this->entity_tag = null;
$this->entity_type = null;
$this->entity_data = array();
$this->entity_finished = false;
$this->text_buffer = '';
$this->last_opener_attributes = array();
}
}
@@ -0,0 +1,45 @@
<?php
namespace WordPress\DataLiberation\EntityReader;
/**
* The Entity Reader ingests content from a source and breaks it down into
* individual "entities" that WordPress understands - posts, comments, metadata, etc.
*/
interface EntityReader {
/**
* Gets the current entity being processed.
*
* @return ImportedEntity|false The current entity, or false if none available
*/
public function get_entity();
/**
* Advances to the next entity in the source content.
*
* This is where each data source implements its own logic for parsing the bytes
* and extracting the next meaningful piece of content.
*
* @return bool Whether we successfully moved to the next entity
*/
public function next_entity();
/**
* Checks if we've processed everything from the source.
*
* @return bool Whether we've processed everything from the source
*/
public function is_finished(): bool;
/**
* Returns a cursor position that can be used to resume processing later.
*
* This allows for processing large imports in chunks without losing your place.
* Not all readers support this yet.
*
* @TODO: Define a general interface for entity readers.
* @return string Position marker for resuming later
*/
public function get_reentrancy_cursor();
}
@@ -0,0 +1,45 @@
<?php
namespace WordPress\DataLiberation\EntityReader;
/**
* The Entity Reader ingests content from a source and breaks it down into
* individual "entities" that WordPress understands - posts, comments, metadata, etc.
*/
interface EntityReader {
/**
* Gets the current entity being processed.
*
* @return ImportedEntity|false The current entity, or false if none available
*/
public function get_entity();
/**
* Advances to the next entity in the source content.
*
* This is where each data source implements its own logic for parsing the bytes
* and extracting the next meaningful piece of content.
*
* @return bool Whether we successfully moved to the next entity
*/
public function next_entity();
/**
* Checks if we've processed everything from the source.
*
* @return bool Whether we've processed everything from the source
*/
public function is_finished(): bool;
/**
* Returns a cursor position that can be used to resume processing later.
*
* This allows for processing large imports in chunks without losing your place.
* Not all readers support this yet.
*
* @TODO: Define a general interface for entity readers.
* @return string Position marker for resuming later
*/
public function get_reentrancy_cursor();
}
@@ -0,0 +1,37 @@
<?php
namespace WordPress\DataLiberation\URL;
use VendorPrefix\Rowbot\URL\URL;
/**
* Value object returned by WPURL::replace_base_url().
*
* - Cast to string to get the updated URL as a string.
* - When the original URL was relative, casting returns a relative string against
* the new base.
*/
class ConvertedUrl {
/** @var URL */
public $new_url;
/** @var string */
public $new_raw_url;
/** @var string|null */
public $new_raw_relative_url;
/** @var bool */
public $was_relative = false;
/**
* Returns the updated URL string. If the original was relative, returns a relative string.
*/
public function __toString(): string {
if ( $this->was_relative ) {
return $this->new_raw_relative_url;
}
return $this->new_raw_url;
}
}
@@ -0,0 +1,94 @@
<?php
namespace WordPress\DataLiberation\URL;
use WordPress\DataLiberation\CSS\CSSProcessor;
/**
* Provides URL specific helpers on top of the CSSProcessor tokenizer.
*/
class CSSURLProcessor {
/**
* @var CSSProcessor
*/
private $processor;
/**
* @param string $css CSS source without wrapping braces.
*/
public function __construct( string $css ) {
$this->processor = CSSProcessor::create( $css );
}
/**
* Moves the cursor to the next URL token, if available.
*
* @return bool
*/
public function next_url(): bool {
while ( $this->processor->next_token() ) {
$type = $this->processor->get_token_type();
// Direct URL token.
if ( CSSProcessor::TOKEN_URL === $type ) {
return true;
}
// url() function with STRING token.
if ( CSSProcessor::TOKEN_FUNCTION === $type &&
0 === strcasecmp( $this->processor->get_token_value(), 'url' ) ) {
// Look ahead for STRING token, skipping whitespace.
while ( $this->processor->next_token() ) {
$inner_type = $this->processor->get_token_type();
if ( CSSProcessor::TOKEN_WHITESPACE === $inner_type ) {
continue; // Skip whitespace.
}
if ( CSSProcessor::TOKEN_STRING === $inner_type ) {
return true; // Found the URL string.
}
// Hit something else (like RIGHT_PAREN or another token).
break;
}
}
}
return false;
}
/**
* Returns the raw (decoded) URL for the current match.
*
* @return string|false
*/
public function get_raw_url() {
$value = $this->processor->get_token_value();
return false !== $value ? $value : false;
}
/**
* Replaces the currently matched URL with a new value.
*
* @param string $new_url Replacement URL without quoting.
* @return bool
*/
public function set_raw_url( string $new_url ): bool {
return $this->processor->set_token_value( $new_url );
}
/**
* Returns the updated CSS with all replacements applied.
*
* @return string
*/
public function get_updated_css(): string {
return $this->processor->get_updated_css();
}
/**
* Determines whether the current URL is a data URI.
*
* @return bool
*/
public function is_data_uri(): bool {
return $this->processor->is_data_uri();
}
}
@@ -0,0 +1,384 @@
<?php
namespace WordPress\DataLiberation\URL;
use WordPress\DataLiberation\BlockMarkup\URL;
use WP_HTML_Text_Replacement;
/**
* Finds string fragments that look like URLs and allows replacing them.
*
* This class implements two stages of detection:
*
* 1. **A "thick" sieve**
* 2. **A "fine" sieve**
*
* The thick sieve uses a regular expression to match URL-like substrings. It matches too
* much and may yield false positives.
*
* The fine sieve filters out invalid candidates using a WHATWG-compliant parser so only
* real URLs are returned.
*
* ## URL Detection
*
* The thick sieve looks for URLs:
*
* * Starting with http://, https://, or //, e.g. //wp.org.
* * With no protocol, e.g. www.wp.org or wp.org/path
*
* Here's a list of matching-related rules, limitations, and assumptions:
*
* ### Protocols
*
* As a site migration tool, this processor only considers URLs with HTTP
* and HTTPS protocols.
*
* ### Domain names
*
* UTF-8 characters in the domain names are supported even if they're
* not encoded as punycode. For example, scanning the text:
*
* > Więcej na łąka.pl
*
* Would yield `łąka.pl`
*
* ### Paths
*
* The path is limited to ASCII characters, as per the URL specification.
* For example, scanning the text:
*
* > Visit the WordPress plugins directory https://w.org/plugins?łąka=1
*
* Would yield `https://w.org/plugins?`, not `https://w.org/plugins?łąka=1`.
* However, scanning this text:
*
* > Visit the WordPress plugins directory https://w.org/plugins?%C5%82%C4%85ka=1
*
* Would yield `https://w.org/plugins?%C5%82%C4%85ka=1`.
*
* ### Parenthesis treatment
*
* This scanner captures parentheses as a part of the path, query, or fragment, except
* when they're seen as the last character in the URL. For example, scanning the text:
*
* > Visit the WordPress plugins directory (https://w.org/plugins)
*
* Would yield `https://w.org/plugins`, but scanning the text:
*
* > Visit the WordPress plugins directory (https://w.org/plug(in)s
*
* Would yield `https://w.org/plug(in)s`.
*
* ### Rejecting URLs with embedded credentials
*
* `https://user:pass@wp.org` is not matched. Rewriting URLs that presume transferable
* credentials is hazardous and rarely correct for migrations.
*
* ### Reject non-HTTP(S) schemes
*
* Out of scope for site moves; all of these are rejected:
* `gopher://site.com`, `blob:afgh2-48189d`, `ahttp://site.com`, `mailto:user@site.com`, `file://asset.zip`.
* If we need additional schemes later, we can add them intentionally.
*
* ### Reject non‑absolute‑looking references
*
* While we do rely on a base URL, inputs like `::`, `/index.html`, `?query` are still ignored.
* Bare-domain forms like `mysite.org/?query` are still matched.
*
* ### Handle trailing punctuation sensibly
*
* `https://mysite.com/path/..` is interpreted as `https://mysite.com/path/` rather than
* collapsing to the origin. A final period is far more likely sentence punctuation than `../`.
* If a user truly writes `https://mysite.com/path/../`, we parse it as expected.
*
* ### Fuzzy matching for malformed ports
*
* * **WHATWG**: `"http://w.org:100000 plugins are in the directory" → failure`.
* * **Inline detection**: `"http://w.org:100000 plugins are in the directory" → "http://w.org/"`
* (truncate at the invalid port).
*
* This is a best‑effort extraction of the valid prefix rather than an all‑or‑nothing rejection.
*
* ### Whitespace handling
*
* * **WHATWG**: `"http://example\t.\norg" → "http://example.org/"`.
* * **Inline detection**: stops at the first whitespace, yielding `"http://example/"`.
*
* This reflects how URLs actually appear in text blocks where whitespace often terminates a link.
*/
class URLInTextProcessor {
private $text;
private $url_starts_at;
private $url_length;
private $bytes_already_parsed = 0;
/**
* @var string
*/
private $matched_url;
/**
* @var URL
*/
private $parsed_url;
private $did_prepend_protocol;
/**
* The base URL for the parsing algorithm.
* See https://url.spec.whatwg.org/.
*
* @var mixed|null
*/
private $base_url;
private $base_protocol;
/**
* The regular expression pattern used for the matchin URL candidates
* from the text.
*
* @var string
*/
private $regex;
/**
* @see \WP_HTML_Tag_Processor
* @var WP_HTML_Text_Replacement[]
*/
private $lexical_updates = array();
/**
* @var bool
* A flag to indicate whether the URL matching should be strict or not.
* If set to true, the matching will be strict, meaning it will only match URLs that strictly adhere to the pattern.
* If set to false, the matching will be more lenient, allowing for potential false positives.
*/
private $strict = false;
public function __construct( $text, $base_url = null ) {
$this->text = $text;
$this->base_url = $base_url;
$this->base_protocol = $base_url ? parse_url( $base_url, PHP_URL_SCHEME ) : null;
$prefix = $this->strict ? '^' : '';
$suffix = $this->strict ? '$' : '';
// Source: https://github.com/vstelmakh/url-highlight/blob/master/src/Matcher/Matcher.php.
$this->regex = '/' . $prefix . '
(?: # scheme
(?<scheme>[a-z0-9\+]+?:)? #
(?:\/*) # The protocol may optionally be followed by one or more slashes
)?
(?: # userinfo
(?:
(?<=\/{2}) # prefixed with \/\/
| # or
(?=[^\p{Sm}\p{Sc}\p{Sk}\p{P}]) # start with not: mathematical, currency, modifier symbol, punctuation
)
(?<userinfo>[^\s<>@\/]+) # not: whitespace, < > @ \/
@ # at
)?
(?=%|[^\p{Z}\p{Sm}\p{Sc}\p{Sk}\p{C}\p{P}]) # followed by valid host char
(?| # host
(?<host> # host prefixed by scheme or userinfo (less strict)
(?<=\/\/|@) # prefixed with \/\/ or @
(?=[^\-]) # label start, not: -
(?:%|[^\p{Z}\p{Sm}\p{Sc}\p{Sk}\p{C}\p{P}]|-){1,63} # label not: whitespace, mathematical, currency, modifier symbol, control point, punctuation | except -
(?<=[^\-]) # label end, not: -
(?: # more label parts
\.
(?=[^\-]) # label start, not: -
(?<tld>(?:[^\p{Z}\p{Sm}\p{Sc}\p{Sk}\p{C}\p{P}]|-){1,63}) # label not: whitespace, mathematical, currency, modifier symbol, control point, punctuation | except -
(?<=[^\-]) # label end, not: -
)*
)
| # or
(?<host> # host with tld (no scheme or userinfo)
(?=[^\-]) # label start, not: -
(?:%|[^\p{Z}\p{Sm}\p{Sc}\p{Sk}\p{C}\p{P}]|-){1,63} # label not: whitespace, mathematical, currency, modifier symbol, control point, punctuation | except -
(?<=[^\-]) # label end, not: -
(?: # more label parts
\.
(?=[^\-]) # label start, not: -
(?:%|[^\p{Z}\p{Sm}\p{Sc}\p{Sk}\p{C}\p{P}]|-){1,63} # label not: whitespace, mathematical, currency, modifier symbol, control point, punctuation | except -
(?<=[^\-]) # label end, not: -
)*
\.(?<tld>\w{2,63}) # tld
)
)
(?:\:(?<port>\d{1,5}(?!\d)))? # port
(?<path> # path, query, fragment
[\/?#] # prefixed with \/ or ? or #
[^\s<>]* # any chars except whitespace and <>
(?<=[^\s<>({\[`!;:\'".,?«»“”‘’]) # end with not a space or some punctuation chars
)?
' . $suffix . '/ixuJ';
}
/**
* @return string
*/
public function next_url() {
while ( true ) {
$this->matched_url = null;
$this->parsed_url = null;
$this->url_starts_at = null;
$this->url_length = null;
$this->did_prepend_protocol = false;
/**
* Thick sieve – eagerly match things that look like URLs but turn out to not be URLs in the end.
*/
$matches = array();
$found = preg_match( $this->regex, $this->text, $matches, PREG_OFFSET_CAPTURE, $this->bytes_already_parsed );
if ( 1 !== $found ) {
return false;
}
$this->matched_url = $matches[0][0];
// Do not consider just :: as a URL.
if ( '::' === $this->matched_url ) {
continue;
}
if (
')' === $this->matched_url[ strlen( $this->matched_url ) - 1 ] ||
'.' === $this->matched_url[ strlen( $this->matched_url ) - 1 ]
) {
$this->matched_url = substr( $this->matched_url, 0, - 1 );
}
$url_starts_at = $matches[0][1];
$this->bytes_already_parsed = $url_starts_at + strlen( $this->matched_url );
$had_protocol = WPURL::has_http_https_protocol( $this->matched_url );
$preprocessed_url = $this->matched_url;
if ( $this->base_url && $this->base_protocol && ! $had_protocol ) {
$preprocessed_url = WPURL::ensure_protocol( $preprocessed_url, $this->base_protocol );
$this->did_prepend_protocol = true;
}
/*
* Extra fine sieve – parse the candidates using a WHATWG-compliant parser to rule out false positives.
*/
$parsed_url = WPURL::parse( $preprocessed_url, $this->base_url );
if ( false === $parsed_url ) {
continue;
}
// Only consider HTTP and HTTPS URLs.
if ( $parsed_url->protocol && ! in_array( $parsed_url->protocol, array( 'http:', 'https:' ), true ) ) {
continue;
}
// Disregard URLs with auth details.
if ( $parsed_url->username || $parsed_url->password ) {
continue;
}
// Additional rigor for URLs that are not explicitly preceded by a double slash.
if ( ! $had_protocol ) {
/*
* Skip TLDs that are not in the public suffix.
* This reduces false positives like `index.html` or `plugins.php`.
*
* See https://publicsuffix.org/.
*/
$last_dot_position = strrpos( $parsed_url->hostname, '.' );
if ( false === $last_dot_position ) {
/*
* Oh, there was no dot in the hostname AND no double slash at
* the beginning! Let's assume this isn't a valid URL and move on.
* @TODO: Explore updating the regular expression above to avoid matching
* URLs without a dot in the hostname when they're not preceeded
* by a protocol.
*/
continue;
}
$tld = substr( $parsed_url->hostname, $last_dot_position + 1 );
if ( ! WPURL::is_known_public_domain( $tld ) ) {
// This TLD is not in the public suffix list. It's not a valid domain name.
continue;
}
}
$this->parsed_url = $parsed_url;
$this->url_starts_at = $url_starts_at;
$this->url_length = strlen( $matches[0][0] );
return true;
}
}
public function get_raw_url() {
return $this->matched_url ?? false;
}
public function get_parsed_url() {
if ( null === $this->parsed_url ) {
return false;
}
return $this->parsed_url;
}
public function set_raw_url( $new_url ) {
if ( null === $this->matched_url ) {
return false;
}
if ( $this->did_prepend_protocol ) {
$new_url = substr( $new_url, strpos( $new_url, '://' ) + 3 );
}
$this->matched_url = $new_url;
$this->lexical_updates[ $this->url_starts_at ] = new WP_HTML_Text_Replacement(
$this->url_starts_at,
$this->url_length,
$new_url
);
return true;
}
private function apply_lexical_updates() {
if ( ! count( $this->lexical_updates ) ) {
return 0;
}
/*
* Attribute updates can be enqueued in any order but updates
* to the document must occur in lexical order; that is, each
* replacement must be made before all others which follow it
* at later string indices in the input document.
*
* Sorting avoid making out-of-order replacements which
* can lead to mangled output, partially-duplicated
* attributes, and overwritten attributes.
*/
ksort( $this->lexical_updates );
$bytes_already_copied = 0;
$output_buffer = '';
foreach ( $this->lexical_updates as $diff ) {
$shift = strlen( $diff->text ) - $diff->length;
// Adjust the cursor position by however much an update affects it.
if ( $diff->start < $this->bytes_already_parsed ) {
$this->bytes_already_parsed += $shift;
}
$output_buffer .= substr( $this->text, $bytes_already_copied, $diff->start - $bytes_already_copied );
if ( $diff->start === $this->url_starts_at ) {
$this->url_starts_at = strlen( $output_buffer );
$this->url_length = strlen( $diff->text );
}
$output_buffer .= $diff->text;
$bytes_already_copied = $diff->start + $diff->length;
}
$this->text = $output_buffer . substr( $this->text, $bytes_already_copied );
$this->lexical_updates = array();
}
public function get_updated_text() {
$this->apply_lexical_updates();
return $this->text;
}
}
@@ -0,0 +1,264 @@
<?php
namespace WordPress\DataLiberation\URL;
use VendorPrefix\Rowbot\URL\URL;
/**
* An abstraction to make swapping the URL parser easier later on.
* We do not need it in the long run. It adds extra overhead of the
* function call – let's remove it once the URL parser is decided.
*/
class WPURL {
public static function parse( $url, $base = null ) {
if ( is_string( $url ) ) {
return URL::parse( $url, $base ) ?? false;
} elseif ( is_a( $url, 'VendorPrefix\Rowbot\URL\URL' ) ) {
return $url;
}
return false;
}
public static function can_parse( $url, $base = null ) {
return URL::canParse( $url, $base );
}
/**
* Replaces the "base" of a URL — scheme, host (and port), and the portion of the path that
* belongs to the old base — with a new base while keeping the remainder of the URL intact.
*
* This is intended for content migrations, where URLs embedded in block markup, HTML attributes,
* or inline text must be moved from one site root to another without losing the rest of the path,
* query, or fragment. It handles simple domain swaps, ports, and deep path bases. When the old
* base includes path segments, only that matched prefix is substituted and the unmatched tail is
* carried over to the target base.
*
* For example:
* * URL: https://example.com/a/b/c/d/e/f/g/h/i/j/page/
* * Old base: https://example.com/a/b/c/d/e/f/
* * New base: https://example.org/docs/
* * Result: https://example.org/docs/g/h/i/j/page/
*
* ## Trailing slash handling
*
* Trailing slash style is preserved from the original URL. If it has no trailing slash, the
* result will also omit the trailing slash and vice versa.
*
* For example, here the final result has no trailing slash:
* * URL: https://example.com/uploads/file.txt
* * Old base: https://example.com/uploads/
* * New base: https://example.org/docs/
* * Result: https://example.org/docs/file.txt
*
* And here it does:
* * URL: https://example.com/uploads/2018/
* * Old base: https://example.com/uploads/
* * New base: https://example.org/docs/
* * Result: https://example.org/docs/2018/
*
* ## URL-encoded path segments
*
* URL-encoded path segments are respected and not inadvertently decoded or re-encoded. Only the
* matched base prefix is considered for alignment, so inputs that contain percent-encoded content
* keep that content exactly as-is in the output. This prevents data corruption in tricky cases such
* as "/~jappleseed/1997.10.1/%2561-reasons-to-migrate-data/" where the "%2561" must remain
* double-escaped after the move.
*
* ## Relative URLs
*
* This method can preserve the relative nature of the original URL. Say you are processing a markup
* that contains `<a href="/uploads/file.txt">`. The original URL string is "/uploads/file.txt",
* and the URL actually resolves to "https://example.com/uploads/file.txt". If you want to replace
* the base URL from "https://example.com/uploads/" to "https://newsite.com/files/" but keep the
* URL relative, you can pass the raw URL string via the "raw_url" option.
*
* For example:
* * URL: https://example.com/uploads/file.txt
* * Raw URL: /uploads/file.txt
* * Old base: https://example.com/uploads/
* * New base: https://example.org/files/
* * Result: /files/file.txt
*
* The method also supports relative inputs commonly found in markup. If you pass the raw URL
* string via the "raw_url" option, the method can infer whether the author originally wrote a
* relative URL like "docs/page.html" or an absolute one. You may also explicitly
* assert relativity with "is_relative" to avoid inference.
*
* @param string|URL $url The URL to replace the base of.
* @param array $options Associative options: old_base_url, new_base_url; optional raw_url.
* @return ConvertedUrl|false Returns a ConvertedUrl value object on success, or false when parsing
* or replacement cannot be performed.
*/
public static function replace_base_url( $url, $options ) {
if ( ! is_array( $options ) ) {
return false;
}
foreach ( array( 'old_base_url', 'new_base_url' ) as $required ) {
if ( ! array_key_exists( $required, $options ) || null === $options[ $required ] ) {
return false;
}
}
$old_base_url = self::parse( $options['old_base_url'] );
$new_base_url = self::parse( $options['new_base_url'] );
$url = self::parse( $url, $old_base_url ? $old_base_url->toString() : null );
if ( false === $old_base_url || false === $new_base_url || false === $url ) {
return false;
}
$updated_url = clone $url;
$updated_url->hostname = $new_base_url->hostname;
$updated_url->protocol = $new_base_url->protocol;
$updated_url->port = $new_base_url->port;
$from_pathname = $url->pathname;
$to_pathname = $new_base_url->pathname;
$base_pathname = $old_base_url->pathname;
if ( $base_pathname !== $to_pathname ) {
$base_pathname_with_trailing_slash = rtrim( $base_pathname, '/' ) . '/';
$decoded_matched_pathname = urldecode_n(
$from_pathname,
strlen( $base_pathname_with_trailing_slash )
);
$to_pathname_with_trailing_slash = rtrim( $to_pathname, '/' ) . '/';
$remaining_pathname = substr(
$decoded_matched_pathname,
strlen( $base_pathname_with_trailing_slash )
);
$updated_url->pathname = $to_pathname_with_trailing_slash . $remaining_pathname;
}
/*
* Stylistic choice – if the updated URL has no trailing slash,
* do not add it to the new URL. The WHATWG URL parser will
* add one automatically if the path is empty, so we have to
* explicitly remove it.
*/
$new_raw_url = $updated_url->toString();
$should_trim_trailing_slash = (
'' !== $from_pathname &&
'/' !== substr( $from_pathname, -1 ) &&
'/' !== $from_pathname &&
'' === $url->search &&
'' === $url->hash
);
if ( $should_trim_trailing_slash ) {
$new_raw_url = rtrim( $new_raw_url, '/' );
}
if ( ! $new_raw_url ) {
// This may technically happen, but does it happen in practice?
return false;
}
$converted_url = new ConvertedUrl();
$converted_url->new_url = $updated_url;
$converted_url->new_raw_url = $new_raw_url;
// Preserve the relative nature of the original URL.
if ( array_key_exists( 'raw_url', $options ) && is_string( $options['raw_url'] ) ) {
if ( ! array_key_exists( 'is_relative', $options ) ) {
$options['is_relative'] = self::can_parse( $options['raw_url'] );
}
if ( $options['is_relative'] ) {
$relative_url = $updated_url->pathname;
// Remove the trailing slash if it's not the root path.
if ( strlen( $relative_url ) > 1 && $should_trim_trailing_slash ) {
$relative_url = rtrim( $relative_url, '/' );
}
if ( '' !== $updated_url->search ) {
$relative_url .= $updated_url->search;
}
if ( '' !== $updated_url->hash ) {
$relative_url .= $updated_url->hash;
}
$converted_url->was_relative = true;
$converted_url->new_raw_relative_url = $relative_url;
}
}
return $converted_url;
}
/**
* Prepends a protocol to any matched URL without the double slash.
*
* Imagine we have a base URL of `https://example.com` and a text like `Visit myblog.com`.
* This Processor would match `myblog.com` as a URL candidate and then the parser
* would parse it as `https://example.com/myblog.com`, which is not what a user would expect.
*
* To get `https://myblog.com`, we need to prepend a protocol and turn that candidate into
* `https://myblog.com` before parsing.
*/
public static function ensure_protocol( $raw_url, $protocol = 'https' ) {
if ( ! self::has_http_https_protocol( $raw_url ) ) {
$raw_url = $protocol . '://' . $raw_url;
}
return $raw_url;
}
/**
* This method only considers http and https protocols.
*/
public static function has_http_https_protocol( $raw_url ) {
return (
(
// Protocol-relative URLs.
strlen( $raw_url ) > 2 &&
'/' === $raw_url[0] &&
'/' === $raw_url[1]
) || (
strlen( $raw_url ) > 5 &&
( 'h' === $raw_url[0] || 'H' === $raw_url[0] ) &&
( 't' === $raw_url[1] || 'T' === $raw_url[1] ) &&
( 't' === $raw_url[2] || 'T' === $raw_url[2] ) &&
( 'p' === $raw_url[3] || 'P' === $raw_url[3] ) &&
':' === $raw_url[4]
) || (
strlen( $raw_url ) > 6 &&
( 'h' === $raw_url[0] || 'H' === $raw_url[0] ) &&
( 't' === $raw_url[1] || 'T' === $raw_url[1] ) &&
( 't' === $raw_url[2] || 'T' === $raw_url[2] ) &&
( 'p' === $raw_url[3] || 'P' === $raw_url[3] ) &&
( 's' === $raw_url[4] || 'S' === $raw_url[4] ) &&
':' === $raw_url[5]
)
);
}
public static function append_path( $base_url, $path ) {
$base_url = self::parse( $base_url );
$base_url->pathname = rtrim( $base_url->pathname, '/' ) . '/' . ltrim( $path, '/' );
return $base_url->toString();
}
/**
* Checks if a TLD is in the known public domain suffix list.
* This reduces false positives like `index.html` or `plugins.php`.
*
* @see https://publicsuffix.org/
*
* @param string $tld The top-level domain to check.
* @return bool True if the TLD is a known public domain, false otherwise.
*/
public static function is_known_public_domain( $tld ) {
static $public_suffix_list = null;
if ( null === $public_suffix_list ) {
$public_suffix_list = require_once __DIR__ . '/public-suffix-list.php';
}
// @TODO: Parse wildcards and exceptions from the public suffix list.
$tld = strtolower( $tld );
return ! empty( $public_suffix_list[ $tld ] ) || 'internal' === $tld;
}
}
@@ -0,0 +1,164 @@
<?php
namespace WordPress\DataLiberation\URL;
use VendorPrefix\Rowbot\URL\URL;
use WordPress\DataLiberation\BlockMarkup\BlockMarkupUrlProcessor;
/**
* Migrate URLs in post content. See WPRewriteUrlsTests for
* specific examples. TODO: A better description.
*
* Example:
*
* ```php
* php > wp_rewrite_urls([
* 'block_markup' => '<!-- wp:image {"src": "http://legacy-blog.com/image.jpg"} -->',
* 'url-mapping' => [
* 'http://legacy-blog.com' => 'https://modern-webstore.org'
* ]
* ])
* <!-- wp:image {"src":"https:\/\/modern-webstore.org\/image.jpg"} -->
* ```
*
* @TODO Use a proper JSON parser and encoder to:
* * Support UTF-16 characters
* * Gracefully handle recoverable encoding issues
* * Avoid changing the whitespace in the same manner as
* we do in WP_HTML_Tag_Processor. e.g. if we start with:
*
* ```html
* <!-- wp:block {"url":"https://w.org"}` -->
* ^ no space here
* ```
*
* then it would be nice to re-encode that block markup also without the space character. This is similar
* to how the tag processor avoids changing parts of the tag it doesn't need to change.
*/
function wp_rewrite_urls( $options ) {
if ( empty( $options['base_url'] ) ) {
// Use first from-url as base_url if not specified.
$from_urls = array_keys( $options['url-mapping'] );
$options['base_url'] = $from_urls[0];
}
$url_mapping = array();
foreach ( $options['url-mapping'] as $from_url_string => $to_url_string ) {
$url_mapping[] = array(
'from_url' => WPURL::parse( $from_url_string ),
'to_url' => WPURL::parse( $to_url_string ),
);
}
$p = new BlockMarkupUrlProcessor( $options['block_markup'], $options['base_url'] );
while ( $p->next_url() ) {
$parsed_url = $p->get_parsed_url();
foreach ( $url_mapping as $mapping ) {
if ( is_child_url_of( $parsed_url, $mapping['from_url'] ) ) {
$p->replace_base_url( $mapping['to_url'] );
break;
}
}
}
return $p->get_updated_html();
}
/**
* Check if a given URL matches the current site URL.
*
* @param URL $child The URL to check.
* @param string $parent_url The current site URL to compare against.
*
* @return bool Whether the URL matches the current site URL.
*/
function is_child_url_of( $child, $parent_url ) {
$parent_url = is_string( $parent_url ) ? WPURL::parse( $parent_url ) : $parent_url;
$child = is_string( $child ) ? WPURL::parse( $child ) : $child;
$child_pathname_no_trailing_slash = rtrim( urldecode( $child->pathname ), '/' );
if ( false === $child || false === $parent_url ) {
return false;
}
if ( $parent_url->hostname !== $child->hostname ) {
return false;
}
if ( $parent_url->protocol !== $child->protocol ) {
return false;
}
$parent_pathname = urldecode( $parent_url->pathname );
return (
// Direct match.
$parent_pathname === $child_pathname_no_trailing_slash ||
$parent_pathname === $child_pathname_no_trailing_slash . '/' ||
// Path prefix.
0 === strncmp( $child_pathname_no_trailing_slash . '/', $parent_pathname, strlen( $parent_pathname ) )
);
}
/**
* Decodes the first n **encoded bytes** a URL-encoded string.
*
* For example, `urldecode_n( '%22is 6 %3C 6?%22 – asked Achilles', 1 )` returns
* '"is 6 %3C 6?%22 – asked Achilles' because only the first encoded byte is decoded.
*
* @param string $input The string to decode.
* @param int $decode_n The number of bytes to decode in $input
*
* @return string The decoded string.
*/
function urldecode_n( $input, $decode_n ) {
// Fast paths: nothing to do.
if ( $decode_n <= 0 || false === strpos( $input, '%' ) ) {
return $input;
}
$result = '';
$at = 0;
while ( true ) {
if ( $at + 3 > strlen( $input ) ) {
break;
}
$last_at = $at;
$at += strcspn( $input, '%', $at );
// Consume bytes except for the percent sign.
$result .= substr( $input, $last_at, $at - $last_at );
// If we've already decoded the requested number of bytes, stop.
if ( strlen( $result ) >= $decode_n ) {
break;
}
++$at;
if ( $at > strlen( $input ) ) {
break;
}
$decodable_length = strspn(
$input,
'0123456789ABCDEFabcdef',
$at,
2
);
if ( 2 === $decodable_length ) {
// Decodes the urlencoded hex sequence from URL.
// Note: This decodes bytes, not characters. It will recover the original byte sequence,
// not necessarily any valid UTF-8 characters.
$result .= chr( hexdec( $input[ $at ] . $input[ $at + 1 ] ) );
$at += 2;
} else {
// Consume the next byte and move on.
$result .= '%';
}
}
$result .= substr( $input, $at );
return $result;
}
@@ -0,0 +1,66 @@
<?php
namespace WordPress\DataLiberation;
/**
* Represents a single entity, whether a WordPress post, post meta,
* a single SQL record, or something entirely different.
*/
class ImportEntity {
const TYPE_POST = 'post';
const TYPE_POST_META = 'post_meta';
const TYPE_COMMENT = 'comment';
const TYPE_COMMENT_META = 'comment_meta';
const TYPE_TERM = 'term';
const TYPE_TAG = 'tag';
const TYPE_CATEGORY = 'category';
const TYPE_USER = 'user';
const TYPE_SITE_OPTION = 'site_option';
const POST_FIELDS = array(
'post_title',
'link',
'guid',
'post_excerpt',
'post_published_at',
'post_author',
'post_content',
'post_excerpt',
'post_id',
'post_status',
'post_date',
'post_date_gmt',
'post_modified',
'post_modified_gmt',
'comment_status',
'ping_status',
'post_name',
'post_parent',
'menu_order',
'post_type',
'post_password',
'is_sticky',
'attachment_url',
);
private $type;
private $data;
public function __construct( $type, $data ) {
$this->type = $type;
$this->data = $data;
}
public function get_type() {
return $this->type;
}
public function get_data() {
return $this->data;
}
public function set_data( $data ) {
$this->data = $data;
}
}
@@ -0,0 +1,4 @@
# Vendor Patches
The libraries in this directory have been downgraded to PHP 7.2 compatibility using Rector
and some manual fixes.
@@ -0,0 +1,469 @@
# Changelog
All notable changes to this project will be documented in this file.
## UNRELEASED (0.12.2)
👌 **Improvements**
- Add missing `RoundingNecessaryException` to the `@throws` annotation of `BigNumber::of()`
## [0.12.1](https://github.com/brick/math/releases/tag/0.12.1) - 2023-11-29
⚡️ **Performance improvements**
- `BigNumber::of()` is now faster, thanks to [@SebastienDug](https://github.com/SebastienDug) in [#77](https://github.com/brick/math/pull/77).
## [0.12.0](https://github.com/brick/math/releases/tag/0.12.0) - 2023-11-26
💥 **Breaking changes**
- Minimum PHP version is now 8.1
- `RoundingMode` is now an `enum`; if you're type-hinting rounding modes, you need to type-hint against `RoundingMode` instead of `int` now
- `BigNumber` classes do not implement the `Serializable` interface anymore (they use the [new custom object serialization mechanism](https://wiki.php.net/rfc/custom_object_serialization))
- The following breaking changes only affect you if you're creating your own `BigNumber` subclasses:
- the return type of `BigNumber::of()` is now `static`
- `BigNumber` has a new abstract method `from()`
- all `public` and `protected` functions of `BigNumber` are now `final`
## [0.11.0](https://github.com/brick/math/releases/tag/0.11.0) - 2023-01-16
💥 **Breaking changes**
- Minimum PHP version is now 8.0
- Methods accepting a union of types are now strongly typed<sup>*</sup>
- `MathException` now extends `Exception` instead of `RuntimeException`
<sup>* You may now run into type errors if you were passing `Stringable` objects to `of()` or any of the methods
internally calling `of()`, with `strict_types` enabled. You can fix this by casting `Stringable` objects to `string`
first.</sup>
## [0.10.2](https://github.com/brick/math/releases/tag/0.10.2) - 2022-08-11
👌 **Improvements**
- `BigRational::toFloat()` now simplifies the fraction before performing division (#73) thanks to @olsavmic
## [0.10.1](https://github.com/brick/math/releases/tag/0.10.1) - 2022-08-02
✨ **New features**
- `BigInteger::gcdMultiple()` returns the GCD of multiple `BigInteger` numbers
## [0.10.0](https://github.com/brick/math/releases/tag/0.10.0) - 2022-06-18
💥 **Breaking changes**
- Minimum PHP version is now 7.4
## [0.9.3](https://github.com/brick/math/releases/tag/0.9.3) - 2021-08-15
🚀 **Compatibility with PHP 8.1**
- Support for custom object serialization; this removes a warning on PHP 8.1 due to the `Serializable` interface being deprecated (#60) thanks @TRowbotham
## [0.9.2](https://github.com/brick/math/releases/tag/0.9.2) - 2021-01-20
🐛 **Bug fix**
- Incorrect results could be returned when using the BCMath calculator, with a default scale set with `bcscale()`, on PHP >= 7.2 (#55).
## [0.9.1](https://github.com/brick/math/releases/tag/0.9.1) - 2020-08-19
✨ **New features**
- `BigInteger::not()` returns the bitwise `NOT` value
🐛 **Bug fixes**
- `BigInteger::toBytes()` could return an incorrect binary representation for some numbers
- The bitwise operations `and()`, `or()`, `xor()` on `BigInteger` could return an incorrect result when the GMP extension is not available
## [0.9.0](https://github.com/brick/math/releases/tag/0.9.0) - 2020-08-18
👌 **Improvements**
- `BigNumber::of()` now accepts `.123` and `123.` formats, both of which return a `BigDecimal`
💥 **Breaking changes**
- Deprecated method `BigInteger::powerMod()` has been removed - use `modPow()` instead
- Deprecated method `BigInteger::parse()` has been removed - use `fromBase()` instead
## [0.8.17](https://github.com/brick/math/releases/tag/0.8.17) - 2020-08-19
🐛 **Bug fix**
- `BigInteger::toBytes()` could return an incorrect binary representation for some numbers
- The bitwise operations `and()`, `or()`, `xor()` on `BigInteger` could return an incorrect result when the GMP extension is not available
## [0.8.16](https://github.com/brick/math/releases/tag/0.8.16) - 2020-08-18
🚑 **Critical fix**
- This version reintroduces the deprecated `BigInteger::parse()` method, that has been removed by mistake in version `0.8.9` and should have lasted for the whole `0.8` release cycle.
✨ **New features**
- `BigInteger::modInverse()` calculates a modular multiplicative inverse
- `BigInteger::fromBytes()` creates a `BigInteger` from a byte string
- `BigInteger::toBytes()` converts a `BigInteger` to a byte string
- `BigInteger::randomBits()` creates a pseudo-random `BigInteger` of a given bit length
- `BigInteger::randomRange()` creates a pseudo-random `BigInteger` between two bounds
💩 **Deprecations**
- `BigInteger::powerMod()` is now deprecated in favour of `modPow()`
## [0.8.15](https://github.com/brick/math/releases/tag/0.8.15) - 2020-04-15
🐛 **Fixes**
- added missing `ext-json` requirement, due to `BigNumber` implementing `JsonSerializable`
⚡️ **Optimizations**
- additional optimization in `BigInteger::remainder()`
## [0.8.14](https://github.com/brick/math/releases/tag/0.8.14) - 2020-02-18
✨ **New features**
- `BigInteger::getLowestSetBit()` returns the index of the rightmost one bit
## [0.8.13](https://github.com/brick/math/releases/tag/0.8.13) - 2020-02-16
✨ **New features**
- `BigInteger::isEven()` tests whether the number is even
- `BigInteger::isOdd()` tests whether the number is odd
- `BigInteger::testBit()` tests if a bit is set
- `BigInteger::getBitLength()` returns the number of bits in the minimal representation of the number
## [0.8.12](https://github.com/brick/math/releases/tag/0.8.12) - 2020-02-03
🛠️ **Maintenance release**
Classes are now annotated for better static analysis with [psalm](https://psalm.dev/).
This is a maintenance release: no bug fixes, no new features, no breaking changes.
## [0.8.11](https://github.com/brick/math/releases/tag/0.8.11) - 2020-01-23
✨ **New feature**
`BigInteger::powerMod()` performs a power-with-modulo operation. Useful for crypto.
## [0.8.10](https://github.com/brick/math/releases/tag/0.8.10) - 2020-01-21
✨ **New feature**
`BigInteger::mod()` returns the **modulo** of two numbers. The *modulo* differs from the *remainder* when the signs of the operands are different.
## [0.8.9](https://github.com/brick/math/releases/tag/0.8.9) - 2020-01-08
⚡️ **Performance improvements**
A few additional optimizations in `BigInteger` and `BigDecimal` when one of the operands can be returned as is. Thanks to @tomtomsen in #24.
## [0.8.8](https://github.com/brick/math/releases/tag/0.8.8) - 2019-04-25
🐛 **Bug fixes**
- `BigInteger::toBase()` could return an empty string for zero values (BCMath & Native calculators only, GMP calculator unaffected)
✨ **New features**
- `BigInteger::toArbitraryBase()` converts a number to an arbitrary base, using a custom alphabet
- `BigInteger::fromArbitraryBase()` converts a string in an arbitrary base, using a custom alphabet, back to a number
These methods can be used as the foundation to convert strings between different bases/alphabets, using BigInteger as an intermediate representation.
💩 **Deprecations**
- `BigInteger::parse()` is now deprecated in favour of `fromBase()`
`BigInteger::fromBase()` works the same way as `parse()`, with 2 minor differences:
- the `$base` parameter is required, it does not default to `10`
- it throws a `NumberFormatException` instead of an `InvalidArgumentException` when the number is malformed
## [0.8.7](https://github.com/brick/math/releases/tag/0.8.7) - 2019-04-20
**Improvements**
- Safer conversion from `float` when using custom locales
- **Much faster** `NativeCalculator` implementation 🚀
You can expect **at least a 3x performance improvement** for common arithmetic operations when using the library on systems without GMP or BCMath; it gets exponentially faster on multiplications with a high number of digits. This is due to calculations now being performed on whole blocks of digits (the block size depending on the platform, 32-bit or 64-bit) instead of digit-by-digit as before.
## [0.8.6](https://github.com/brick/math/releases/tag/0.8.6) - 2019-04-11
**New method**
`BigNumber::sum()` returns the sum of one or more numbers.
## [0.8.5](https://github.com/brick/math/releases/tag/0.8.5) - 2019-02-12
**Bug fix**: `of()` factory methods could fail when passing a `float` in environments using a `LC_NUMERIC` locale with a decimal separator other than `'.'` (#20).
Thanks @manowark 👍
## [0.8.4](https://github.com/brick/math/releases/tag/0.8.4) - 2018-12-07
**New method**
`BigDecimal::sqrt()` calculates the square root of a decimal number, to a given scale.
## [0.8.3](https://github.com/brick/math/releases/tag/0.8.3) - 2018-12-06
**New method**
`BigInteger::sqrt()` calculates the square root of a number (thanks @peter279k).
**New exception**
`NegativeNumberException` is thrown when calling `sqrt()` on a negative number.
## [0.8.2](https://github.com/brick/math/releases/tag/0.8.2) - 2018-11-08
**Performance update**
- Further improvement of `toInt()` performance
- `NativeCalculator` can now perform some multiplications more efficiently
## [0.8.1](https://github.com/brick/math/releases/tag/0.8.1) - 2018-11-07
Performance optimization of `toInt()` methods.
## [0.8.0](https://github.com/brick/math/releases/tag/0.8.0) - 2018-10-13
**Breaking changes**
The following deprecated methods have been removed. Use the new method name instead:
| Method removed | Replacement method |
| --- | --- |
| `BigDecimal::getIntegral()` | `BigDecimal::getIntegralPart()` |
| `BigDecimal::getFraction()` | `BigDecimal::getFractionalPart()` |
---
**New features**
`BigInteger` has been augmented with 5 new methods for bitwise operations:
| New method | Description |
| --- | --- |
| `and()` | performs a bitwise `AND` operation on two numbers |
| `or()` | performs a bitwise `OR` operation on two numbers |
| `xor()` | performs a bitwise `XOR` operation on two numbers |
| `shiftedLeft()` | returns the number shifted left by a number of bits |
| `shiftedRight()` | returns the number shifted right by a number of bits |
Thanks to @DASPRiD 👍
## [0.7.3](https://github.com/brick/math/releases/tag/0.7.3) - 2018-08-20
**New method:** `BigDecimal::hasNonZeroFractionalPart()`
**Renamed/deprecated methods:**
- `BigDecimal::getIntegral()` has been renamed to `getIntegralPart()` and is now deprecated
- `BigDecimal::getFraction()` has been renamed to `getFractionalPart()` and is now deprecated
## [0.7.2](https://github.com/brick/math/releases/tag/0.7.2) - 2018-07-21
**Performance update**
`BigInteger::parse()` and `toBase()` now use GMP's built-in base conversion features when available.
## [0.7.1](https://github.com/brick/math/releases/tag/0.7.1) - 2018-03-01
This is a maintenance release, no code has been changed.
- When installed with `--no-dev`, the autoloader does not autoload tests anymore
- Tests and other files unnecessary for production are excluded from the dist package
This will help make installations more compact.
## [0.7.0](https://github.com/brick/math/releases/tag/0.7.0) - 2017-10-02
Methods renamed:
- `BigNumber:sign()` has been renamed to `getSign()`
- `BigDecimal::unscaledValue()` has been renamed to `getUnscaledValue()`
- `BigDecimal::scale()` has been renamed to `getScale()`
- `BigDecimal::integral()` has been renamed to `getIntegral()`
- `BigDecimal::fraction()` has been renamed to `getFraction()`
- `BigRational::numerator()` has been renamed to `getNumerator()`
- `BigRational::denominator()` has been renamed to `getDenominator()`
Classes renamed:
- `ArithmeticException` has been renamed to `MathException`
## [0.6.2](https://github.com/brick/math/releases/tag/0.6.2) - 2017-10-02
The base class for all exceptions is now `MathException`.
`ArithmeticException` has been deprecated, and will be removed in 0.7.0.
## [0.6.1](https://github.com/brick/math/releases/tag/0.6.1) - 2017-10-02
A number of methods have been renamed:
- `BigNumber:sign()` is deprecated; use `getSign()` instead
- `BigDecimal::unscaledValue()` is deprecated; use `getUnscaledValue()` instead
- `BigDecimal::scale()` is deprecated; use `getScale()` instead
- `BigDecimal::integral()` is deprecated; use `getIntegral()` instead
- `BigDecimal::fraction()` is deprecated; use `getFraction()` instead
- `BigRational::numerator()` is deprecated; use `getNumerator()` instead
- `BigRational::denominator()` is deprecated; use `getDenominator()` instead
The old methods will be removed in version 0.7.0.
## [0.6.0](https://github.com/brick/math/releases/tag/0.6.0) - 2017-08-25
- Minimum PHP version is now [7.1](https://gophp71.org/); for PHP 5.6 and PHP 7.0 support, use version `0.5`
- Deprecated method `BigDecimal::withScale()` has been removed; use `toScale()` instead
- Method `BigNumber::toInteger()` has been renamed to `toInt()`
## [0.5.4](https://github.com/brick/math/releases/tag/0.5.4) - 2016-10-17
`BigNumber` classes now implement [JsonSerializable](http://php.net/manual/en/class.jsonserializable.php).
The JSON output is always a string.
## [0.5.3](https://github.com/brick/math/releases/tag/0.5.3) - 2016-03-31
This is a bugfix release. Dividing by a negative power of 1 with the same scale as the dividend could trigger an incorrect optimization which resulted in a wrong result. See #6.
## [0.5.2](https://github.com/brick/math/releases/tag/0.5.2) - 2015-08-06
The `$scale` parameter of `BigDecimal::dividedBy()` is now optional again.
## [0.5.1](https://github.com/brick/math/releases/tag/0.5.1) - 2015-07-05
**New method: `BigNumber::toScale()`**
This allows to convert any `BigNumber` to a `BigDecimal` with a given scale, using rounding if necessary.
## [0.5.0](https://github.com/brick/math/releases/tag/0.5.0) - 2015-07-04
**New features**
- Common `BigNumber` interface for all classes, with the following methods:
- `sign()` and derived methods (`isZero()`, `isPositive()`, ...)
- `compareTo()` and derived methods (`isEqualTo()`, `isGreaterThan()`, ...) that work across different `BigNumber` types
- `toBigInteger()`, `toBigDecimal()`, `toBigRational`() conversion methods
- `toInteger()` and `toFloat()` conversion methods to native types
- Unified `of()` behaviour: every class now accepts any type of number, provided that it can be safely converted to the current type
- New method: `BigDecimal::exactlyDividedBy()`; this method automatically computes the scale of the result, provided that the division yields a finite number of digits
- New methods: `BigRational::quotient()` and `remainder()`
- Fine-grained exceptions: `DivisionByZeroException`, `RoundingNecessaryException`, `NumberFormatException`
- Factory methods `zero()`, `one()` and `ten()` available in all classes
- Rounding mode reintroduced in `BigInteger::dividedBy()`
This release also comes with many performance improvements.
---
**Breaking changes**
- `BigInteger`:
- `getSign()` is renamed to `sign()`
- `toString()` is renamed to `toBase()`
- `BigInteger::dividedBy()` now throws an exception by default if the remainder is not zero; use `quotient()` to get the previous behaviour
- `BigDecimal`:
- `getSign()` is renamed to `sign()`
- `getUnscaledValue()` is renamed to `unscaledValue()`
- `getScale()` is renamed to `scale()`
- `getIntegral()` is renamed to `integral()`
- `getFraction()` is renamed to `fraction()`
- `divideAndRemainder()` is renamed to `quotientAndRemainder()`
- `dividedBy()` now takes a **mandatory** `$scale` parameter **before** the rounding mode
- `toBigInteger()` does not accept a `$roundingMode` parameter anymore
- `toBigRational()` does not simplify the fraction anymore; explicitly add `->simplified()` to get the previous behaviour
- `BigRational`:
- `getSign()` is renamed to `sign()`
- `getNumerator()` is renamed to `numerator()`
- `getDenominator()` is renamed to `denominator()`
- `of()` is renamed to `nd()`, while `parse()` is renamed to `of()`
- Miscellaneous:
- `ArithmeticException` is moved to an `Exception\` sub-namespace
- `of()` factory methods now throw `NumberFormatException` instead of `InvalidArgumentException`
## [0.4.3](https://github.com/brick/math/releases/tag/0.4.3) - 2016-03-31
Backport of two bug fixes from the 0.5 branch:
- `BigInteger::parse()` did not always throw `InvalidArgumentException` as expected
- Dividing by a negative power of 1 with the same scale as the dividend could trigger an incorrect optimization which resulted in a wrong result. See #6.
## [0.4.2](https://github.com/brick/math/releases/tag/0.4.2) - 2015-06-16
New method: `BigDecimal::stripTrailingZeros()`
## [0.4.1](https://github.com/brick/math/releases/tag/0.4.1) - 2015-06-12
Introducing a `BigRational` class, to perform calculations on fractions of any size.
## [0.4.0](https://github.com/brick/math/releases/tag/0.4.0) - 2015-06-12
Rounding modes have been removed from `BigInteger`, and are now a concept specific to `BigDecimal`.
`BigInteger::dividedBy()` now always returns the quotient of the division.
## [0.3.5](https://github.com/brick/math/releases/tag/0.3.5) - 2016-03-31
Backport of two bug fixes from the 0.5 branch:
- `BigInteger::parse()` did not always throw `InvalidArgumentException` as expected
- Dividing by a negative power of 1 with the same scale as the dividend could trigger an incorrect optimization which resulted in a wrong result. See #6.
## [0.3.4](https://github.com/brick/math/releases/tag/0.3.4) - 2015-06-11
New methods:
- `BigInteger::remainder()` returns the remainder of a division only
- `BigInteger::gcd()` returns the greatest common divisor of two numbers
## [0.3.3](https://github.com/brick/math/releases/tag/0.3.3) - 2015-06-07
Fix `toString()` not handling negative numbers.
## [0.3.2](https://github.com/brick/math/releases/tag/0.3.2) - 2015-06-07
`BigInteger` and `BigDecimal` now have a `getSign()` method that returns:
- `-1` if the number is negative
- `0` if the number is zero
- `1` if the number is positive
## [0.3.1](https://github.com/brick/math/releases/tag/0.3.1) - 2015-06-05
Minor performance improvements
## [0.3.0](https://github.com/brick/math/releases/tag/0.3.0) - 2015-06-04
The `$roundingMode` and `$scale` parameters have been swapped in `BigDecimal::dividedBy()`.
## [0.2.2](https://github.com/brick/math/releases/tag/0.2.2) - 2015-06-04
Stronger immutability guarantee for `BigInteger` and `BigDecimal`.
So far, it would have been possible to break immutability of these classes by calling the `unserialize()` internal function. This release fixes that.
## [0.2.1](https://github.com/brick/math/releases/tag/0.2.1) - 2015-06-02
Added `BigDecimal::divideAndRemainder()`
## [0.2.0](https://github.com/brick/math/releases/tag/0.2.0) - 2015-05-22
- `min()` and `max()` do not accept an `array` anymore, but a variable number of parameters
- **minimum PHP version is now 5.6**
- continuous integration with PHP 7
## [0.1.1](https://github.com/brick/math/releases/tag/0.1.1) - 2014-09-01
- Added `BigInteger::power()`
- Added HHVM support
## [0.1.0](https://github.com/brick/math/releases/tag/0.1.0) - 2014-08-31
First beta release.
@@ -0,0 +1,20 @@
The MIT License (MIT)
Copyright (c) 2013-present Benjamin Morel
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@@ -0,0 +1,39 @@
{
"name": "brick/math",
"description": "Arbitrary-precision arithmetic library",
"type": "library",
"keywords": [
"Brick",
"Math",
"Mathematics",
"Arbitrary-precision",
"Arithmetic",
"BigInteger",
"BigDecimal",
"BigRational",
"BigNumber",
"Bignum",
"Decimal",
"Rational",
"Integer"
],
"license": "MIT",
"require": {
"php": "^7.2"
},
"require-dev": {
"phpunit/phpunit": "^10.1",
"php-coveralls/php-coveralls": "^2.2",
"vimeo/psalm": "5.25.0"
},
"autoload": {
"psr-4": {
"VendorPrefix\\Brick\\Math\\": "src/"
}
},
"autoload-dev": {
"psr-4": {
"VendorPrefix\\Brick\\Math\\Tests\\": "tests/"
}
}
}
@@ -0,0 +1,766 @@
<?php
declare(strict_types=1);
namespace VendorPrefix\Brick\Math;
use VendorPrefix\Brick\Math\Exception\DivisionByZeroException;
use VendorPrefix\Brick\Math\Exception\MathException;
use VendorPrefix\Brick\Math\Exception\NegativeNumberException;
use VendorPrefix\Brick\Math\Internal\Calculator;
/**
* Immutable, arbitrary-precision signed decimal numbers.
*
* @psalm-immutable
*/
final class BigDecimal extends BigNumber
{
/**
* The unscaled value of this decimal number.
*
* This is a string of digits with an optional leading minus sign.
* No leading zero must be present.
* No leading minus sign must be present if the value is 0.
* @readonly
* @var string
*/
private $value;
/**
* The scale (number of digits after the decimal point) of this decimal number.
*
* This must be zero or more.
* @readonly
* @var int
*/
private $scale;
/**
* Protected constructor. Use a factory method to obtain an instance.
*
* @param string $value The unscaled value, validated.
* @param int $scale The scale, validated.
*/
protected function __construct(string $value, int $scale = 0)
{
$this->value = $value;
$this->scale = $scale;
}
/**
* @psalm-pure
* @return static
*/
protected static function from(BigNumber $number)
{
return $number->toBigDecimal();
}
/**
* Creates a BigDecimal from an unscaled value and a scale.
*
* Example: `(12345, 3)` will result in the BigDecimal `12.345`.
*
* @param BigNumber|int|float|string $value The unscaled value. Must be convertible to a BigInteger.
* @param int $scale The scale of the number, positive or zero.
*
* @throws \InvalidArgumentException If the scale is negative.
*
* @psalm-pure
*/
public static function ofUnscaledValue($value, int $scale = 0) : BigDecimal
{
if ($scale < 0) {
throw new \InvalidArgumentException('The scale cannot be negative.');
}
return new BigDecimal((string) BigInteger::of($value), $scale);
}
/**
* Returns a BigDecimal representing zero, with a scale of zero.
*
* @psalm-pure
*/
public static function zero() : BigDecimal
{
/**
* @psalm-suppress ImpureStaticVariable
* @var BigDecimal|null $zero
*/
static $zero;
if ($zero === null) {
$zero = new BigDecimal('0');
}
return $zero;
}
/**
* Returns a BigDecimal representing one, with a scale of zero.
*
* @psalm-pure
*/
public static function one() : BigDecimal
{
/**
* @psalm-suppress ImpureStaticVariable
* @var BigDecimal|null $one
*/
static $one;
if ($one === null) {
$one = new BigDecimal('1');
}
return $one;
}
/**
* Returns a BigDecimal representing ten, with a scale of zero.
*
* @psalm-pure
*/
public static function ten() : BigDecimal
{
/**
* @psalm-suppress ImpureStaticVariable
* @var BigDecimal|null $ten
*/
static $ten;
if ($ten === null) {
$ten = new BigDecimal('10');
}
return $ten;
}
/**
* Returns the sum of this number and the given one.
*
* The result has a scale of `max($this->scale, $that->scale)`.
*
* @param BigNumber|int|float|string $that The number to add. Must be convertible to a BigDecimal.
*
* @throws MathException If the number is not valid, or is not convertible to a BigDecimal.
*/
public function plus($that) : BigDecimal
{
$that = BigDecimal::of($that);
if ($that->value === '0' && $that->scale <= $this->scale) {
return $this;
}
if ($this->value === '0' && $this->scale <= $that->scale) {
return $that;
}
[$a, $b] = $this->scaleValues($this, $that);
$value = Calculator::get()->add($a, $b);
$scale = $this->scale > $that->scale ? $this->scale : $that->scale;
return new BigDecimal($value, $scale);
}
/**
* Returns the difference of this number and the given one.
*
* The result has a scale of `max($this->scale, $that->scale)`.
*
* @param BigNumber|int|float|string $that The number to subtract. Must be convertible to a BigDecimal.
*
* @throws MathException If the number is not valid, or is not convertible to a BigDecimal.
*/
public function minus($that) : BigDecimal
{
$that = BigDecimal::of($that);
if ($that->value === '0' && $that->scale <= $this->scale) {
return $this;
}
[$a, $b] = $this->scaleValues($this, $that);
$value = Calculator::get()->sub($a, $b);
$scale = $this->scale > $that->scale ? $this->scale : $that->scale;
return new BigDecimal($value, $scale);
}
/**
* Returns the product of this number and the given one.
*
* The result has a scale of `$this->scale + $that->scale`.
*
* @param BigNumber|int|float|string $that The multiplier. Must be convertible to a BigDecimal.
*
* @throws MathException If the multiplier is not a valid number, or is not convertible to a BigDecimal.
*/
public function multipliedBy($that) : BigDecimal
{
$that = BigDecimal::of($that);
if ($that->value === '1' && $that->scale === 0) {
return $this;
}
if ($this->value === '1' && $this->scale === 0) {
return $that;
}
$value = Calculator::get()->mul($this->value, $that->value);
$scale = $this->scale + $that->scale;
return new BigDecimal($value, $scale);
}
/**
* Returns the result of the division of this number by the given one, at the given scale.
*
* @param BigNumber|int|float|string $that The divisor.
* @param int|null $scale The desired scale, or null to use the scale of this number.
* @param mixed $roundingMode An optional rounding mode, defaults to UNNECESSARY.
*
* @throws \InvalidArgumentException If the scale or rounding mode is invalid.
* @throws MathException If the number is invalid, is zero, or rounding was necessary.
* @param \VendorPrefix\Brick\Math\RoundingMode::* $roundingMode
*/
public function dividedBy($that, ?int $scale = null, $roundingMode = RoundingMode::UNNECESSARY) : BigDecimal
{
$that = BigDecimal::of($that);
if ($that->isZero()) {
throw DivisionByZeroException::divisionByZero();
}
if ($scale === null) {
$scale = $this->scale;
} elseif ($scale < 0) {
throw new \InvalidArgumentException('Scale cannot be negative.');
}
if ($that->value === '1' && $that->scale === 0 && $scale === $this->scale) {
return $this;
}
$p = $this->valueWithMinScale($that->scale + $scale);
$q = $that->valueWithMinScale($this->scale - $scale);
$result = Calculator::get()->divRound($p, $q, $roundingMode);
return new BigDecimal($result, $scale);
}
/**
* Returns the exact result of the division of this number by the given one.
*
* The scale of the result is automatically calculated to fit all the fraction digits.
*
* @param BigNumber|int|float|string $that The divisor. Must be convertible to a BigDecimal.
*
* @throws MathException If the divisor is not a valid number, is not convertible to a BigDecimal, is zero,
* or the result yields an infinite number of digits.
*/
public function exactlyDividedBy($that) : BigDecimal
{
$that = BigDecimal::of($that);
if ($that->value === '0') {
throw DivisionByZeroException::divisionByZero();
}
[, $b] = $this->scaleValues($this, $that);
$d = \rtrim($b, '0');
$scale = \strlen($b) - \strlen($d);
$calculator = Calculator::get();
foreach ([5, 2] as $prime) {
for (;;) {
$lastDigit = (int) $d[-1];
if ($lastDigit % $prime !== 0) {
break;
}
$d = $calculator->divQ($d, (string) $prime);
$scale++;
}
}
return $this->dividedBy($that, $scale)->stripTrailingZeros();
}
/**
* Returns this number exponentiated to the given value.
*
* The result has a scale of `$this->scale * $exponent`.
*
* @throws \InvalidArgumentException If the exponent is not in the range 0 to 1,000,000.
*/
public function power(int $exponent) : BigDecimal
{
if ($exponent === 0) {
return BigDecimal::one();
}
if ($exponent === 1) {
return $this;
}
if ($exponent < 0 || $exponent > Calculator::MAX_POWER) {
throw new \InvalidArgumentException(\sprintf(
'The exponent %d is not in the range 0 to %d.',
$exponent,
Calculator::MAX_POWER
));
}
return new BigDecimal(Calculator::get()->pow($this->value, $exponent), $this->scale * $exponent);
}
/**
* Returns the quotient of the division of this number by the given one.
*
* The quotient has a scale of `0`.
*
* @param BigNumber|int|float|string $that The divisor. Must be convertible to a BigDecimal.
*
* @throws MathException If the divisor is not a valid decimal number, or is zero.
*/
public function quotient($that) : BigDecimal
{
$that = BigDecimal::of($that);
if ($that->isZero()) {
throw DivisionByZeroException::divisionByZero();
}
$p = $this->valueWithMinScale($that->scale);
$q = $that->valueWithMinScale($this->scale);
$quotient = Calculator::get()->divQ($p, $q);
return new BigDecimal($quotient, 0);
}
/**
* Returns the remainder of the division of this number by the given one.
*
* The remainder has a scale of `max($this->scale, $that->scale)`.
*
* @param BigNumber|int|float|string $that The divisor. Must be convertible to a BigDecimal.
*
* @throws MathException If the divisor is not a valid decimal number, or is zero.
*/
public function remainder($that) : BigDecimal
{
$that = BigDecimal::of($that);
if ($that->isZero()) {
throw DivisionByZeroException::divisionByZero();
}
$p = $this->valueWithMinScale($that->scale);
$q = $that->valueWithMinScale($this->scale);
$remainder = Calculator::get()->divR($p, $q);
$scale = $this->scale > $that->scale ? $this->scale : $that->scale;
return new BigDecimal($remainder, $scale);
}
/**
* Returns the quotient and remainder of the division of this number by the given one.
*
* The quotient has a scale of `0`, and the remainder has a scale of `max($this->scale, $that->scale)`.
*
* @param BigNumber|int|float|string $that The divisor. Must be convertible to a BigDecimal.
*
* @return BigDecimal[] An array containing the quotient and the remainder.
*
* @psalm-return array{BigDecimal, BigDecimal}
*
* @throws MathException If the divisor is not a valid decimal number, or is zero.
*/
public function quotientAndRemainder($that) : array
{
$that = BigDecimal::of($that);
if ($that->isZero()) {
throw DivisionByZeroException::divisionByZero();
}
$p = $this->valueWithMinScale($that->scale);
$q = $that->valueWithMinScale($this->scale);
[$quotient, $remainder] = Calculator::get()->divQR($p, $q);
$scale = $this->scale > $that->scale ? $this->scale : $that->scale;
$quotient = new BigDecimal($quotient, 0);
$remainder = new BigDecimal($remainder, $scale);
return [$quotient, $remainder];
}
/**
* Returns the square root of this number, rounded down to the given number of decimals.
*
* @throws \InvalidArgumentException If the scale is negative.
* @throws NegativeNumberException If this number is negative.
*/
public function sqrt(int $scale) : BigDecimal
{
if ($scale < 0) {
throw new \InvalidArgumentException('Scale cannot be negative.');
}
if ($this->value === '0') {
return new BigDecimal('0', $scale);
}
if ($this->value[0] === '-') {
throw new NegativeNumberException('Cannot calculate the square root of a negative number.');
}
$value = $this->value;
$addDigits = 2 * $scale - $this->scale;
if ($addDigits > 0) {
// add zeros
$value .= \str_repeat('0', $addDigits);
} elseif ($addDigits < 0) {
// trim digits
if (-$addDigits >= \strlen($this->value)) {
// requesting a scale too low, will always yield a zero result
return new BigDecimal('0', $scale);
}
$value = \substr($value, 0, $addDigits);
}
$value = Calculator::get()->sqrt($value);
return new BigDecimal($value, $scale);
}
/**
* Returns a copy of this BigDecimal with the decimal point moved $n places to the left.
*/
public function withPointMovedLeft(int $n) : BigDecimal
{
if ($n === 0) {
return $this;
}
if ($n < 0) {
return $this->withPointMovedRight(-$n);
}
return new BigDecimal($this->value, $this->scale + $n);
}
/**
* Returns a copy of this BigDecimal with the decimal point moved $n places to the right.
*/
public function withPointMovedRight(int $n) : BigDecimal
{
if ($n === 0) {
return $this;
}
if ($n < 0) {
return $this->withPointMovedLeft(-$n);
}
$value = $this->value;
$scale = $this->scale - $n;
if ($scale < 0) {
if ($value !== '0') {
$value .= \str_repeat('0', -$scale);
}
$scale = 0;
}
return new BigDecimal($value, $scale);
}
/**
* Returns a copy of this BigDecimal with any trailing zeros removed from the fractional part.
*/
public function stripTrailingZeros() : BigDecimal
{
if ($this->scale === 0) {
return $this;
}
$trimmedValue = \rtrim($this->value, '0');
if ($trimmedValue === '') {
return BigDecimal::zero();
}
$trimmableZeros = \strlen($this->value) - \strlen($trimmedValue);
if ($trimmableZeros === 0) {
return $this;
}
if ($trimmableZeros > $this->scale) {
$trimmableZeros = $this->scale;
}
$value = \substr($this->value, 0, -$trimmableZeros);
$scale = $this->scale - $trimmableZeros;
return new BigDecimal($value, $scale);
}
/**
* Returns the absolute value of this number.
*/
public function abs() : BigDecimal
{
return $this->isNegative() ? $this->negated() : $this;
}
/**
* Returns the negated value of this number.
*/
public function negated() : BigDecimal
{
return new BigDecimal(Calculator::get()->neg($this->value), $this->scale);
}
/**
* @param \VendorPrefix\Brick\Math\BigNumber|int|float|string $that
*/
public function compareTo($that) : int
{
$that = BigNumber::of($that);
if ($that instanceof BigInteger) {
$that = $that->toBigDecimal();
}
if ($that instanceof BigDecimal) {
[$a, $b] = $this->scaleValues($this, $that);
return Calculator::get()->cmp($a, $b);
}
return - $that->compareTo($this);
}
public function getSign() : int
{
return ($this->value === '0') ? 0 : (($this->value[0] === '-') ? -1 : 1);
}
public function getUnscaledValue() : BigInteger
{
return self::newBigInteger($this->value);
}
public function getScale() : int
{
return $this->scale;
}
/**
* Returns a string representing the integral part of this decimal number.
*
* Example: `-123.456` => `-123`.
*/
public function getIntegralPart() : string
{
if ($this->scale === 0) {
return $this->value;
}
$value = $this->getUnscaledValueWithLeadingZeros();
return \substr($value, 0, -$this->scale);
}
/**
* Returns a string representing the fractional part of this decimal number.
*
* If the scale is zero, an empty string is returned.
*
* Examples: `-123.456` => '456', `123` => ''.
*/
public function getFractionalPart() : string
{
if ($this->scale === 0) {
return '';
}
$value = $this->getUnscaledValueWithLeadingZeros();
return \substr($value, -$this->scale);
}
/**
* Returns whether this decimal number has a non-zero fractional part.
*/
public function hasNonZeroFractionalPart() : bool
{
return $this->getFractionalPart() !== \str_repeat('0', $this->scale);
}
public function toBigInteger() : BigInteger
{
$zeroScaleDecimal = $this->scale === 0 ? $this : $this->dividedBy(1, 0);
return self::newBigInteger($zeroScaleDecimal->value);
}
public function toBigDecimal() : BigDecimal
{
return $this;
}
public function toBigRational() : BigRational
{
$numerator = self::newBigInteger($this->value);
$denominator = self::newBigInteger('1' . \str_repeat('0', $this->scale));
return self::newBigRational($numerator, $denominator, false);
}
/**
* @param mixed $roundingMode
*/
public function toScale(int $scale, $roundingMode = RoundingMode::UNNECESSARY) : BigDecimal
{
if ($scale === $this->scale) {
return $this;
}
return $this->dividedBy(BigDecimal::one(), $scale, $roundingMode);
}
public function toInt() : int
{
return $this->toBigInteger()->toInt();
}
public function toFloat() : float
{
return (float) (string) $this;
}
public function __toString() : string
{
if ($this->scale === 0) {
return $this->value;
}
$value = $this->getUnscaledValueWithLeadingZeros();
return \substr($value, 0, -$this->scale) . '.' . \substr($value, -$this->scale);
}
/**
* This method is required for serializing the object and SHOULD NOT be accessed directly.
*
* @internal
*
* @return array{value: string, scale: int}
*/
public function __serialize(): array
{
return ['value' => $this->value, 'scale' => $this->scale];
}
/**
* This method is only here to allow unserializing the object and cannot be accessed directly.
*
* @internal
* @psalm-suppress RedundantPropertyInitializationCheck
*
* @param array{value: string, scale: int} $data
*
* @throws \LogicException
*/
public function __unserialize(array $data): void
{
if (isset($this->value)) {
throw new \LogicException('__unserialize() is an internal function, it must not be called directly.');
}
$this->value = $data['value'];
$this->scale = $data['scale'];
}
/**
* Puts the internal values of the given decimal numbers on the same scale.
*
* @return array{string, string} The scaled integer values of $x and $y.
*/
private function scaleValues(BigDecimal $x, BigDecimal $y) : array
{
$a = $x->value;
$b = $y->value;
if ($b !== '0' && $x->scale > $y->scale) {
$b .= \str_repeat('0', $x->scale - $y->scale);
} elseif ($a !== '0' && $x->scale < $y->scale) {
$a .= \str_repeat('0', $y->scale - $x->scale);
}
return [$a, $b];
}
private function valueWithMinScale(int $scale) : string
{
$value = $this->value;
if ($this->value !== '0' && $scale > $this->scale) {
$value .= \str_repeat('0', $scale - $this->scale);
}
return $value;
}
/**
* Adds leading zeros if necessary to the unscaled value to represent the full decimal number.
*/
private function getUnscaledValueWithLeadingZeros() : string
{
$value = $this->value;
$targetLength = $this->scale + 1;
$negative = ($value[0] === '-');
$length = \strlen($value);
if ($negative) {
$length--;
}
if ($length >= $targetLength) {
return $this->value;
}
if ($negative) {
$value = \substr($value, 1);
}
$value = \str_pad($value, $targetLength, '0', STR_PAD_LEFT);
if ($negative) {
$value = '-' . $value;
}
return $value;
}
}
@@ -0,0 +1,527 @@
<?php
declare(strict_types=1);
namespace VendorPrefix\Brick\Math;
use VendorPrefix\Brick\Math\Exception\DivisionByZeroException;
use VendorPrefix\Brick\Math\Exception\MathException;
use VendorPrefix\Brick\Math\Exception\NumberFormatException;
use VendorPrefix\Brick\Math\Exception\RoundingNecessaryException;
/**
* Common interface for arbitrary-precision rational numbers.
*
* @psalm-immutable
*/
abstract class BigNumber implements \JsonSerializable
{
/**
* The regular expression used to parse integer or decimal numbers.
*/
private const PARSE_REGEXP_NUMERICAL =
'/^' .
'(?<sign>[\-\+])?' .
'(?<integral>[0-9]+)?' .
'(?<point>\.)?' .
'(?<fractional>[0-9]+)?' .
'(?:[eE](?<exponent>[\-\+]?[0-9]+))?' .
'$/';
/**
* The regular expression used to parse rational numbers.
*/
private const PARSE_REGEXP_RATIONAL =
'/^' .
'(?<sign>[\-\+])?' .
'(?<numerator>[0-9]+)' .
'\/?' .
'(?<denominator>[0-9]+)' .
'$/';
/**
* Creates a BigNumber of the given value.
*
* The concrete return type is dependent on the given value, with the following rules:
*
* - BigNumber instances are returned as is
* - integer numbers are returned as BigInteger
* - floating point numbers are converted to a string then parsed as such
* - strings containing a `/` character are returned as BigRational
* - strings containing a `.` character or using an exponential notation are returned as BigDecimal
* - strings containing only digits with an optional leading `+` or `-` sign are returned as BigInteger
*
* @throws NumberFormatException If the format of the number is not valid.
* @throws DivisionByZeroException If the value represents a rational number with a denominator of zero.
* @throws RoundingNecessaryException If the value cannot be converted to an instance of the subclass without rounding.
*
* @psalm-pure
* @param \VendorPrefix\Brick\Math\BigNumber|int|float|string $value
* @return static
*/
final public static function of($value)
{
$value = self::_of($value);
if (static::class === BigNumber::class) {
// https://github.com/vimeo/psalm/issues/10309
assert($value instanceof static);
return $value;
}
return static::from($value);
}
/**
* @throws NumberFormatException If the format of the number is not valid.
* @throws DivisionByZeroException If the value represents a rational number with a denominator of zero.
*
* @psalm-pure
* @param \VendorPrefix\Brick\Math\BigNumber|int|float|string $value
*/
private static function _of($value) : BigNumber
{
if ($value instanceof BigNumber) {
return $value;
}
if (\is_int($value)) {
return new BigInteger((string) $value);
}
if (is_float($value)) {
$value = (string) $value;
}
if (strpos($value, '/') !== false) {
// Rational number
if (\preg_match(self::PARSE_REGEXP_RATIONAL, $value, $matches, PREG_UNMATCHED_AS_NULL) !== 1) {
throw NumberFormatException::invalidFormat($value);
}
$sign = $matches['sign'];
$numerator = $matches['numerator'];
$denominator = $matches['denominator'];
assert($numerator !== null);
assert($denominator !== null);
$numerator = self::cleanUp($sign, $numerator);
$denominator = self::cleanUp(null, $denominator);
if ($denominator === '0') {
throw DivisionByZeroException::denominatorMustNotBeZero();
}
return new BigRational(
new BigInteger($numerator),
new BigInteger($denominator),
false
);
} else {
// Integer or decimal number
if (\preg_match(self::PARSE_REGEXP_NUMERICAL, $value, $matches, PREG_UNMATCHED_AS_NULL) !== 1) {
throw NumberFormatException::invalidFormat($value);
}
$sign = $matches['sign'];
$point = $matches['point'];
$integral = $matches['integral'];
$fractional = $matches['fractional'];
$exponent = $matches['exponent'];
if ($integral === null && $fractional === null) {
throw NumberFormatException::invalidFormat($value);
}
if ($integral === null) {
$integral = '0';
}
if ($point !== null || $exponent !== null) {
$fractional = ($fractional ?? '');
$exponent = ($exponent !== null) ? (int)$exponent : 0;
if ($exponent === PHP_INT_MIN || $exponent === PHP_INT_MAX) {
throw new NumberFormatException('Exponent too large.');
}
$unscaledValue = self::cleanUp($sign, $integral . $fractional);
$scale = \strlen($fractional) - $exponent;
if ($scale < 0) {
if ($unscaledValue !== '0') {
$unscaledValue .= \str_repeat('0', -$scale);
}
$scale = 0;
}
return new BigDecimal($unscaledValue, $scale);
}
$integral = self::cleanUp($sign, $integral);
return new BigInteger($integral);
}
}
/**
* Overridden by subclasses to convert a BigNumber to an instance of the subclass.
*
* @throws RoundingNecessaryException If the value cannot be converted.
*
* @psalm-pure
* @return static
*/
abstract protected static function from(BigNumber $number);
/**
* Proxy method to access BigInteger's protected constructor from sibling classes.
*
* @internal
* @psalm-pure
*/
final protected function newBigInteger(string $value) : BigInteger
{
return new BigInteger($value);
}
/**
* Proxy method to access BigDecimal's protected constructor from sibling classes.
*
* @internal
* @psalm-pure
*/
final protected function newBigDecimal(string $value, int $scale = 0) : BigDecimal
{
return new BigDecimal($value, $scale);
}
/**
* Proxy method to access BigRational's protected constructor from sibling classes.
*
* @internal
* @psalm-pure
*/
final protected function newBigRational(BigInteger $numerator, BigInteger $denominator, bool $checkDenominator) : BigRational
{
return new BigRational($numerator, $denominator, $checkDenominator);
}
/**
* Returns the minimum of the given values.
*
* @param BigNumber|int|float|string ...$values The numbers to compare. All the numbers need to be convertible
* to an instance of the class this method is called on.
*
* @throws \InvalidArgumentException If no values are given.
* @throws MathException If an argument is not valid.
*
* @psalm-pure
* @return static
*/
final public static function min(...$values)
{
$min = null;
foreach ($values as $value) {
$value = static::of($value);
if ($min === null || $value->isLessThan($min)) {
$min = $value;
}
}
if ($min === null) {
throw new \InvalidArgumentException(__METHOD__ . '() expects at least one value.');
}
return $min;
}
/**
* Returns the maximum of the given values.
*
* @param BigNumber|int|float|string ...$values The numbers to compare. All the numbers need to be convertible
* to an instance of the class this method is called on.
*
* @throws \InvalidArgumentException If no values are given.
* @throws MathException If an argument is not valid.
*
* @psalm-pure
* @return static
*/
final public static function max(...$values)
{
$max = null;
foreach ($values as $value) {
$value = static::of($value);
if ($max === null || $value->isGreaterThan($max)) {
$max = $value;
}
}
if ($max === null) {
throw new \InvalidArgumentException(__METHOD__ . '() expects at least one value.');
}
return $max;
}
/**
* Returns the sum of the given values.
*
* @param BigNumber|int|float|string ...$values The numbers to add. All the numbers need to be convertible
* to an instance of the class this method is called on.
*
* @throws \InvalidArgumentException If no values are given.
* @throws MathException If an argument is not valid.
*
* @psalm-pure
* @return static
*/
final public static function sum(...$values)
{
/** @var static|null $sum */
$sum = null;
foreach ($values as $value) {
$value = static::of($value);
$sum = $sum === null ? $value : self::add($sum, $value);
}
if ($sum === null) {
throw new \InvalidArgumentException(__METHOD__ . '() expects at least one value.');
}
return $sum;
}
/**
* Adds two BigNumber instances in the correct order to avoid a RoundingNecessaryException.
*
* @todo This could be better resolved by creating an abstract protected method in BigNumber, and leaving to
* concrete classes the responsibility to perform the addition themselves or delegate it to the given number,
* depending on their ability to perform the operation. This will also require a version bump because we're
* potentially breaking custom BigNumber implementations (if any...)
*
* @psalm-pure
*/
private static function add(BigNumber $a, BigNumber $b) : BigNumber
{
if ($a instanceof BigRational) {
return $a->plus($b);
}
if ($b instanceof BigRational) {
return $b->plus($a);
}
if ($a instanceof BigDecimal) {
return $a->plus($b);
}
if ($b instanceof BigDecimal) {
return $b->plus($a);
}
/** @var BigInteger $a */
return $a->plus($b);
}
/**
* Removes optional leading zeros and applies sign.
*
* @param string|null $sign The sign, '+' or '-', optional. Null is allowed for convenience and treated as '+'.
* @param string $number The number, validated as a non-empty string of digits.
*
* @psalm-pure
*/
private static function cleanUp(?string $sign, string $number) : string
{
$number = \ltrim($number, '0');
if ($number === '') {
return '0';
}
return $sign === '-' ? '-' . $number : $number;
}
/**
* Checks if this number is equal to the given one.
* @param \VendorPrefix\Brick\Math\BigNumber|int|float|string $that
*/
final public function isEqualTo($that) : bool
{
return $this->compareTo($that) === 0;
}
/**
* Checks if this number is strictly lower than the given one.
* @param \VendorPrefix\Brick\Math\BigNumber|int|float|string $that
*/
final public function isLessThan($that) : bool
{
return $this->compareTo($that) < 0;
}
/**
* Checks if this number is lower than or equal to the given one.
* @param \VendorPrefix\Brick\Math\BigNumber|int|float|string $that
*/
final public function isLessThanOrEqualTo($that) : bool
{
return $this->compareTo($that) <= 0;
}
/**
* Checks if this number is strictly greater than the given one.
* @param \VendorPrefix\Brick\Math\BigNumber|int|float|string $that
*/
final public function isGreaterThan($that) : bool
{
return $this->compareTo($that) > 0;
}
/**
* Checks if this number is greater than or equal to the given one.
* @param \VendorPrefix\Brick\Math\BigNumber|int|float|string $that
*/
final public function isGreaterThanOrEqualTo($that) : bool
{
return $this->compareTo($that) >= 0;
}
/**
* Checks if this number equals zero.
*/
final public function isZero() : bool
{
return $this->getSign() === 0;
}
/**
* Checks if this number is strictly negative.
*/
final public function isNegative() : bool
{
return $this->getSign() < 0;
}
/**
* Checks if this number is negative or zero.
*/
final public function isNegativeOrZero() : bool
{
return $this->getSign() <= 0;
}
/**
* Checks if this number is strictly positive.
*/
final public function isPositive() : bool
{
return $this->getSign() > 0;
}
/**
* Checks if this number is positive or zero.
*/
final public function isPositiveOrZero() : bool
{
return $this->getSign() >= 0;
}
/**
* Returns the sign of this number.
*
* @psalm-return -1|0|1
*
* @return int -1 if the number is negative, 0 if zero, 1 if positive.
*/
abstract public function getSign() : int;
/**
* Compares this number to the given one.
*
* @psalm-return -1|0|1
*
* @return int -1 if `$this` is lower than, 0 if equal to, 1 if greater than `$that`.
*
* @throws MathException If the number is not valid.
* @param \VendorPrefix\Brick\Math\BigNumber|int|float|string $that
*/
abstract public function compareTo($that) : int;
/**
* Converts this number to a BigInteger.
*
* @throws RoundingNecessaryException If this number cannot be converted to a BigInteger without rounding.
*/
abstract public function toBigInteger() : BigInteger;
/**
* Converts this number to a BigDecimal.
*
* @throws RoundingNecessaryException If this number cannot be converted to a BigDecimal without rounding.
*/
abstract public function toBigDecimal() : BigDecimal;
/**
* Converts this number to a BigRational.
*/
abstract public function toBigRational() : BigRational;
/**
* Converts this number to a BigDecimal with the given scale, using rounding if necessary.
*
* @param int $scale The scale of the resulting `BigDecimal`.
* @param mixed $roundingMode An optional rounding mode, defaults to UNNECESSARY.
*
* @throws RoundingNecessaryException If this number cannot be converted to the given scale without rounding.
* This only applies when RoundingMode::UNNECESSARY is used.
* @param \VendorPrefix\Brick\Math\RoundingMode::* $roundingMode
*/
abstract public function toScale(int $scale, $roundingMode = RoundingMode::UNNECESSARY) : BigDecimal;
/**
* Returns the exact value of this number as a native integer.
*
* If this number cannot be converted to a native integer without losing precision, an exception is thrown.
* Note that the acceptable range for an integer depends on the platform and differs for 32-bit and 64-bit.
*
* @throws MathException If this number cannot be exactly converted to a native integer.
*/
abstract public function toInt() : int;
/**
* Returns an approximation of this number as a floating-point value.
*
* Note that this method can discard information as the precision of a floating-point value
* is inherently limited.
*
* If the number is greater than the largest representable floating point number, positive infinity is returned.
* If the number is less than the smallest representable floating point number, negative infinity is returned.
*/
abstract public function toFloat() : float;
/**
* Returns a string representation of this number.
*
* The output of this method can be parsed by the `of()` factory method;
* this will yield an object equal to this one, without any information loss.
*/
abstract public function __toString() : string;
final public function jsonSerialize() : string
{
return $this->__toString();
}
}
@@ -0,0 +1,421 @@
<?php
declare(strict_types=1);
namespace VendorPrefix\Brick\Math;
use VendorPrefix\Brick\Math\Exception\DivisionByZeroException;
use VendorPrefix\Brick\Math\Exception\MathException;
use VendorPrefix\Brick\Math\Exception\NumberFormatException;
use VendorPrefix\Brick\Math\Exception\RoundingNecessaryException;
/**
* An arbitrarily large rational number.
*
* This class is immutable.
*
* @psalm-immutable
*/
final class BigRational extends BigNumber
{
/**
* The numerator.
* @readonly
* @var \VendorPrefix\Brick\Math\BigInteger
*/
private $numerator;
/**
* The denominator. Always strictly positive.
* @readonly
* @var \VendorPrefix\Brick\Math\BigInteger
*/
private $denominator;
/**
* Protected constructor. Use a factory method to obtain an instance.
*
* @param BigInteger $numerator The numerator.
* @param BigInteger $denominator The denominator.
* @param bool $checkDenominator Whether to check the denominator for negative and zero.
*
* @throws DivisionByZeroException If the denominator is zero.
*/
protected function __construct(BigInteger $numerator, BigInteger $denominator, bool $checkDenominator)
{
if ($checkDenominator) {
if ($denominator->isZero()) {
throw DivisionByZeroException::denominatorMustNotBeZero();
}
if ($denominator->isNegative()) {
$numerator = $numerator->negated();
$denominator = $denominator->negated();
}
}
$this->numerator = $numerator;
$this->denominator = $denominator;
}
/**
* @psalm-pure
* @return static
*/
protected static function from(BigNumber $number)
{
return $number->toBigRational();
}
/**
* Creates a BigRational out of a numerator and a denominator.
*
* If the denominator is negative, the signs of both the numerator and the denominator
* will be inverted to ensure that the denominator is always positive.
*
* @param BigNumber|int|float|string $numerator The numerator. Must be convertible to a BigInteger.
* @param BigNumber|int|float|string $denominator The denominator. Must be convertible to a BigInteger.
*
* @throws NumberFormatException If an argument does not represent a valid number.
* @throws RoundingNecessaryException If an argument represents a non-integer number.
* @throws DivisionByZeroException If the denominator is zero.
*
* @psalm-pure
*/
public static function nd($numerator, $denominator): BigRational
{
$numerator = BigInteger::of($numerator);
$denominator = BigInteger::of($denominator);
return new BigRational($numerator, $denominator, true);
}
/**
* Returns a BigRational representing zero.
*
* @psalm-pure
*/
public static function zero() : BigRational
{
/**
* @psalm-suppress ImpureStaticVariable
* @var BigRational|null $zero
*/
static $zero;
if ($zero === null) {
$zero = new BigRational(BigInteger::zero(), BigInteger::one(), false);
}
return $zero;
}
/**
* Returns a BigRational representing one.
*
* @psalm-pure
*/
public static function one() : BigRational
{
/**
* @psalm-suppress ImpureStaticVariable
* @var BigRational|null $one
*/
static $one;
if ($one === null) {
$one = new BigRational(BigInteger::one(), BigInteger::one(), false);
}
return $one;
}
/**
* Returns a BigRational representing ten.
*
* @psalm-pure
*/
public static function ten() : BigRational
{
/**
* @psalm-suppress ImpureStaticVariable
* @var BigRational|null $ten
*/
static $ten;
if ($ten === null) {
$ten = new BigRational(BigInteger::ten(), BigInteger::one(), false);
}
return $ten;
}
public function getNumerator() : BigInteger
{
return $this->numerator;
}
public function getDenominator() : BigInteger
{
return $this->denominator;
}
/**
* Returns the quotient of the division of the numerator by the denominator.
*/
public function quotient() : BigInteger
{
return $this->numerator->quotient($this->denominator);
}
/**
* Returns the remainder of the division of the numerator by the denominator.
*/
public function remainder() : BigInteger
{
return $this->numerator->remainder($this->denominator);
}
/**
* Returns the quotient and remainder of the division of the numerator by the denominator.
*
* @return BigInteger[]
*
* @psalm-return array{BigInteger, BigInteger}
*/
public function quotientAndRemainder() : array
{
return $this->numerator->quotientAndRemainder($this->denominator);
}
/**
* Returns the sum of this number and the given one.
*
* @param BigNumber|int|float|string $that The number to add.
*
* @throws MathException If the number is not valid.
*/
public function plus($that) : BigRational
{
$that = BigRational::of($that);
$numerator = $this->numerator->multipliedBy($that->denominator);
$numerator = $numerator->plus($that->numerator->multipliedBy($this->denominator));
$denominator = $this->denominator->multipliedBy($that->denominator);
return new BigRational($numerator, $denominator, false);
}
/**
* Returns the difference of this number and the given one.
*
* @param BigNumber|int|float|string $that The number to subtract.
*
* @throws MathException If the number is not valid.
*/
public function minus($that) : BigRational
{
$that = BigRational::of($that);
$numerator = $this->numerator->multipliedBy($that->denominator);
$numerator = $numerator->minus($that->numerator->multipliedBy($this->denominator));
$denominator = $this->denominator->multipliedBy($that->denominator);
return new BigRational($numerator, $denominator, false);
}
/**
* Returns the product of this number and the given one.
*
* @param BigNumber|int|float|string $that The multiplier.
*
* @throws MathException If the multiplier is not a valid number.
*/
public function multipliedBy($that) : BigRational
{
$that = BigRational::of($that);
$numerator = $this->numerator->multipliedBy($that->numerator);
$denominator = $this->denominator->multipliedBy($that->denominator);
return new BigRational($numerator, $denominator, false);
}
/**
* Returns the result of the division of this number by the given one.
*
* @param BigNumber|int|float|string $that The divisor.
*
* @throws MathException If the divisor is not a valid number, or is zero.
*/
public function dividedBy($that) : BigRational
{
$that = BigRational::of($that);
$numerator = $this->numerator->multipliedBy($that->denominator);
$denominator = $this->denominator->multipliedBy($that->numerator);
return new BigRational($numerator, $denominator, true);
}
/**
* Returns this number exponentiated to the given value.
*
* @throws \InvalidArgumentException If the exponent is not in the range 0 to 1,000,000.
*/
public function power(int $exponent) : BigRational
{
if ($exponent === 0) {
$one = BigInteger::one();
return new BigRational($one, $one, false);
}
if ($exponent === 1) {
return $this;
}
return new BigRational(
$this->numerator->power($exponent),
$this->denominator->power($exponent),
false
);
}
/**
* Returns the reciprocal of this BigRational.
*
* The reciprocal has the numerator and denominator swapped.
*
* @throws DivisionByZeroException If the numerator is zero.
*/
public function reciprocal() : BigRational
{
return new BigRational($this->denominator, $this->numerator, true);
}
/**
* Returns the absolute value of this BigRational.
*/
public function abs() : BigRational
{
return new BigRational($this->numerator->abs(), $this->denominator, false);
}
/**
* Returns the negated value of this BigRational.
*/
public function negated() : BigRational
{
return new BigRational($this->numerator->negated(), $this->denominator, false);
}
/**
* Returns the simplified value of this BigRational.
*/
public function simplified() : BigRational
{
$gcd = $this->numerator->gcd($this->denominator);
$numerator = $this->numerator->quotient($gcd);
$denominator = $this->denominator->quotient($gcd);
return new BigRational($numerator, $denominator, false);
}
/**
* @param \VendorPrefix\Brick\Math\BigNumber|int|float|string $that
*/
public function compareTo($that) : int
{
return $this->minus($that)->getSign();
}
public function getSign() : int
{
return $this->numerator->getSign();
}
public function toBigInteger() : BigInteger
{
$simplified = $this->simplified();
if (! $simplified->denominator->isEqualTo(1)) {
throw new RoundingNecessaryException('This rational number cannot be represented as an integer value without rounding.');
}
return $simplified->numerator;
}
public function toBigDecimal() : BigDecimal
{
return $this->numerator->toBigDecimal()->exactlyDividedBy($this->denominator);
}
public function toBigRational() : BigRational
{
return $this;
}
/**
* @param mixed $roundingMode
*/
public function toScale(int $scale, $roundingMode = RoundingMode::UNNECESSARY) : BigDecimal
{
return $this->numerator->toBigDecimal()->dividedBy($this->denominator, $scale, $roundingMode);
}
public function toInt() : int
{
return $this->toBigInteger()->toInt();
}
public function toFloat() : float
{
$simplified = $this->simplified();
return $simplified->numerator->toFloat() / $simplified->denominator->toFloat();
}
public function __toString() : string
{
$numerator = (string) $this->numerator;
$denominator = (string) $this->denominator;
if ($denominator === '1') {
return $numerator;
}
return $this->numerator . '/' . $this->denominator;
}
/**
* This method is required for serializing the object and SHOULD NOT be accessed directly.
*
* @internal
*
* @return array{numerator: BigInteger, denominator: BigInteger}
*/
public function __serialize(): array
{
return ['numerator' => $this->numerator, 'denominator' => $this->denominator];
}
/**
* This method is only here to allow unserializing the object and cannot be accessed directly.
*
* @internal
* @psalm-suppress RedundantPropertyInitializationCheck
*
* @param array{numerator: BigInteger, denominator: BigInteger} $data
*
* @throws \LogicException
*/
public function __unserialize(array $data): void
{
if (isset($this->numerator)) {
throw new \LogicException('__unserialize() is an internal function, it must not be called directly.');
}
$this->numerator = $data['numerator'];
$this->denominator = $data['denominator'];
}
}
@@ -0,0 +1,35 @@
<?php
declare(strict_types=1);
namespace VendorPrefix\Brick\Math\Exception;
/**
* Exception thrown when a division by zero occurs.
*/
class DivisionByZeroException extends MathException
{
/**
* @psalm-pure
*/
public static function divisionByZero() : DivisionByZeroException
{
return new self('Division by zero.');
}
/**
* @psalm-pure
*/
public static function modulusMustNotBeZero() : DivisionByZeroException
{
return new self('The modulus must not be zero.');
}
/**
* @psalm-pure
*/
public static function denominatorMustNotBeZero() : DivisionByZeroException
{
return new self('The denominator of a rational number cannot be zero.');
}
}
@@ -0,0 +1,23 @@
<?php
declare(strict_types=1);
namespace VendorPrefix\Brick\Math\Exception;
use VendorPrefix\Brick\Math\BigInteger;
/**
* Exception thrown when an integer overflow occurs.
*/
class IntegerOverflowException extends MathException
{
/**
* @psalm-pure
*/
public static function toIntOverflow(BigInteger $value) : IntegerOverflowException
{
$message = '%s is out of range %d to %d and cannot be represented as an integer.';
return new self(\sprintf($message, (string) $value, PHP_INT_MIN, PHP_INT_MAX));
}
}
@@ -0,0 +1,12 @@
<?php
declare(strict_types=1);
namespace VendorPrefix\Brick\Math\Exception;
/**
* Base class for all math exceptions.
*/
class MathException extends \Exception
{
}
@@ -0,0 +1,12 @@
<?php
declare(strict_types=1);
namespace VendorPrefix\Brick\Math\Exception;
/**
* Exception thrown when attempting to perform an unsupported operation, such as a square root, on a negative number.
*/
class NegativeNumberException extends MathException
{
}
@@ -0,0 +1,38 @@
<?php
declare(strict_types=1);
namespace VendorPrefix\Brick\Math\Exception;
/**
* Exception thrown when attempting to create a number from a string with an invalid format.
*/
class NumberFormatException extends MathException
{
public static function invalidFormat(string $value) : self
{
return new self(\sprintf('The given value "%s" does not represent a valid number.', $value));
}
/**
* @param string $char The failing character.
*
* @psalm-pure
*/
public static function charNotInAlphabet(string $char) : self
{
$ord = \ord($char);
if ($ord < 32 || $ord > 126) {
$char = \strtoupper(\dechex($ord));
if ($ord < 10) {
$char = '0' . $char;
}
} else {
$char = '"' . $char . '"';
}
return new self(\sprintf('Char %s is not a valid character in the given alphabet.', $char));
}
}
@@ -0,0 +1,19 @@
<?php
declare(strict_types=1);
namespace VendorPrefix\Brick\Math\Exception;
/**
* Exception thrown when a number cannot be represented at the requested scale without rounding.
*/
class RoundingNecessaryException extends MathException
{
/**
* @psalm-pure
*/
public static function roundingNecessary() : RoundingNecessaryException
{
return new self('Rounding is necessary to represent the result of the operation at this scale.');
}
}
@@ -0,0 +1,682 @@
<?php
declare(strict_types=1);
namespace VendorPrefix\Brick\Math\Internal;
use VendorPrefix\Brick\Math\Exception\RoundingNecessaryException;
use VendorPrefix\Brick\Math\RoundingMode;
/**
* Performs basic operations on arbitrary size integers.
*
* Unless otherwise specified, all parameters must be validated as non-empty strings of digits,
* without leading zero, and with an optional leading minus sign if the number is not zero.
*
* Any other parameter format will lead to undefined behaviour.
* All methods must return strings respecting this format, unless specified otherwise.
*
* @internal
*
* @psalm-immutable
*/
abstract class Calculator
{
/**
* The maximum exponent value allowed for the pow() method.
*/
public const MAX_POWER = 1000000;
/**
* The alphabet for converting from and to base 2 to 36, lowercase.
*/
public const ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz';
/**
* The Calculator instance in use.
* @var \VendorPrefix\Brick\Math\Internal\Calculator|null
*/
private static $instance;
/**
* Sets the Calculator instance to use.
*
* An instance is typically set only in unit tests: the autodetect is usually the best option.
*
* @param Calculator|null $calculator The calculator instance, or NULL to revert to autodetect.
*/
final public static function set(?Calculator $calculator) : void
{
self::$instance = $calculator;
}
/**
* Returns the Calculator instance to use.
*
* If none has been explicitly set, the fastest available implementation will be returned.
*
* @psalm-pure
* @psalm-suppress ImpureStaticProperty
*/
final public static function get() : Calculator
{
if (self::$instance === null) {
/** @psalm-suppress ImpureMethodCall */
self::$instance = self::detect();
}
return self::$instance;
}
/**
* Returns the fastest available Calculator implementation.
*
* @codeCoverageIgnore
*/
private static function detect() : Calculator
{
if (\extension_loaded('gmp')) {
return new Calculator\GmpCalculator();
}
if (\extension_loaded('bcmath')) {
return new Calculator\BcMathCalculator();
}
return new Calculator\NativeCalculator();
}
/**
* Extracts the sign & digits of the operands.
*
* @return array{bool, bool, string, string} Whether $a and $b are negative, followed by their digits.
*/
final protected function init(string $a, string $b) : array
{
return [
$aNeg = ($a[0] === '-'),
$bNeg = ($b[0] === '-'),
$aNeg ? \substr($a, 1) : $a,
$bNeg ? \substr($b, 1) : $b,
];
}
/**
* Returns the absolute value of a number.
*/
final public function abs(string $n) : string
{
return ($n[0] === '-') ? \substr($n, 1) : $n;
}
/**
* Negates a number.
*/
final public function neg(string $n) : string
{
if ($n === '0') {
return '0';
}
if ($n[0] === '-') {
return \substr($n, 1);
}
return '-' . $n;
}
/**
* Compares two numbers.
*
* @psalm-return -1|0|1
*
* @return int -1 if the first number is less than, 0 if equal to, 1 if greater than the second number.
*/
final public function cmp(string $a, string $b) : int
{
[$aNeg, $bNeg, $aDig, $bDig] = $this->init($a, $b);
if ($aNeg && ! $bNeg) {
return -1;
}
if ($bNeg && ! $aNeg) {
return 1;
}
$aLen = \strlen($aDig);
$bLen = \strlen($bDig);
if ($aLen < $bLen) {
$result = -1;
} elseif ($aLen > $bLen) {
$result = 1;
} else {
$result = $aDig <=> $bDig;
}
return $aNeg ? -$result : $result;
}
/**
* Adds two numbers.
*/
abstract public function add(string $a, string $b) : string;
/**
* Subtracts two numbers.
*/
abstract public function sub(string $a, string $b) : string;
/**
* Multiplies two numbers.
*/
abstract public function mul(string $a, string $b) : string;
/**
* Returns the quotient of the division of two numbers.
*
* @param string $a The dividend.
* @param string $b The divisor, must not be zero.
*
* @return string The quotient.
*/
abstract public function divQ(string $a, string $b) : string;
/**
* Returns the remainder of the division of two numbers.
*
* @param string $a The dividend.
* @param string $b The divisor, must not be zero.
*
* @return string The remainder.
*/
abstract public function divR(string $a, string $b) : string;
/**
* Returns the quotient and remainder of the division of two numbers.
*
* @param string $a The dividend.
* @param string $b The divisor, must not be zero.
*
* @return array{string, string} An array containing the quotient and remainder.
*/
abstract public function divQR(string $a, string $b) : array;
/**
* Exponentiates a number.
*
* @param string $a The base number.
* @param int $e The exponent, validated as an integer between 0 and MAX_POWER.
*
* @return string The power.
*/
abstract public function pow(string $a, int $e) : string;
/**
* @param string $b The modulus; must not be zero.
*/
public function mod(string $a, string $b) : string
{
return $this->divR($this->add($this->divR($a, $b), $b), $b);
}
/**
* Returns the modular multiplicative inverse of $x modulo $m.
*
* If $x has no multiplicative inverse mod m, this method must return null.
*
* This method can be overridden by the concrete implementation if the underlying library has built-in support.
*
* @param string $m The modulus; must not be negative or zero.
*/
public function modInverse(string $x, string $m) : ?string
{
if ($m === '1') {
return '0';
}
$modVal = $x;
if ($x[0] === '-' || ($this->cmp($this->abs($x), $m) >= 0)) {
$modVal = $this->mod($x, $m);
}
[$g, $x] = $this->gcdExtended($modVal, $m);
if ($g !== '1') {
return null;
}
return $this->mod($this->add($this->mod($x, $m), $m), $m);
}
/**
* Raises a number into power with modulo.
*
* @param string $base The base number; must be positive or zero.
* @param string $exp The exponent; must be positive or zero.
* @param string $mod The modulus; must be strictly positive.
*/
abstract public function modPow(string $base, string $exp, string $mod) : string;
/**
* Returns the greatest common divisor of the two numbers.
*
* This method can be overridden by the concrete implementation if the underlying library
* has built-in support for GCD calculations.
*
* @return string The GCD, always positive, or zero if both arguments are zero.
*/
public function gcd(string $a, string $b) : string
{
if ($a === '0') {
return $this->abs($b);
}
if ($b === '0') {
return $this->abs($a);
}
return $this->gcd($b, $this->divR($a, $b));
}
/**
* @return array{string, string, string} GCD, X, Y
*/
private function gcdExtended(string $a, string $b) : array
{
if ($a === '0') {
return [$b, '0', '1'];
}
[$gcd, $x1, $y1] = $this->gcdExtended($this->mod($b, $a), $a);
$x = $this->sub($y1, $this->mul($this->divQ($b, $a), $x1));
$y = $x1;
return [$gcd, $x, $y];
}
/**
* Returns the square root of the given number, rounded down.
*
* The result is the largest x such that x² ≤ n.
* The input MUST NOT be negative.
*/
abstract public function sqrt(string $n) : string;
/**
* Converts a number from an arbitrary base.
*
* This method can be overridden by the concrete implementation if the underlying library
* has built-in support for base conversion.
*
* @param string $number The number, positive or zero, non-empty, case-insensitively validated for the given base.
* @param int $base The base of the number, validated from 2 to 36.
*
* @return string The converted number, following the Calculator conventions.
*/
public function fromBase(string $number, int $base) : string
{
return $this->fromArbitraryBase(\strtolower($number), self::ALPHABET, $base);
}
/**
* Converts a number to an arbitrary base.
*
* This method can be overridden by the concrete implementation if the underlying library
* has built-in support for base conversion.
*
* @param string $number The number to convert, following the Calculator conventions.
* @param int $base The base to convert to, validated from 2 to 36.
*
* @return string The converted number, lowercase.
*/
public function toBase(string $number, int $base) : string
{
$negative = ($number[0] === '-');
if ($negative) {
$number = \substr($number, 1);
}
$number = $this->toArbitraryBase($number, self::ALPHABET, $base);
if ($negative) {
return '-' . $number;
}
return $number;
}
/**
* Converts a non-negative number in an arbitrary base using a custom alphabet, to base 10.
*
* @param string $number The number to convert, validated as a non-empty string,
* containing only chars in the given alphabet/base.
* @param string $alphabet The alphabet that contains every digit, validated as 2 chars minimum.
* @param int $base The base of the number, validated from 2 to alphabet length.
*
* @return string The number in base 10, following the Calculator conventions.
*/
final public function fromArbitraryBase(string $number, string $alphabet, int $base) : string
{
// remove leading "zeros"
$number = \ltrim($number, $alphabet[0]);
if ($number === '') {
return '0';
}
// optimize for "one"
if ($number === $alphabet[1]) {
return '1';
}
$result = '0';
$power = '1';
$base = (string) $base;
for ($i = \strlen($number) - 1; $i >= 0; $i--) {
$index = \strpos($alphabet, $number[$i]);
if ($index !== 0) {
$result = $this->add($result, ($index === 1)
? $power
: $this->mul($power, (string) $index)
);
}
if ($i !== 0) {
$power = $this->mul($power, $base);
}
}
return $result;
}
/**
* Converts a non-negative number to an arbitrary base using a custom alphabet.
*
* @param string $number The number to convert, positive or zero, following the Calculator conventions.
* @param string $alphabet The alphabet that contains every digit, validated as 2 chars minimum.
* @param int $base The base to convert to, validated from 2 to alphabet length.
*
* @return string The converted number in the given alphabet.
*/
final public function toArbitraryBase(string $number, string $alphabet, int $base) : string
{
if ($number === '0') {
return $alphabet[0];
}
$base = (string) $base;
$result = '';
while ($number !== '0') {
[$number, $remainder] = $this->divQR($number, $base);
$remainder = (int) $remainder;
$result .= $alphabet[$remainder];
}
return \strrev($result);
}
/**
* Performs a rounded division.
*
* Rounding is performed when the remainder of the division is not zero.
*
* @param string $a The dividend.
* @param string $b The divisor, must not be zero.
* @param mixed $roundingMode The rounding mode.
*
* @throws \InvalidArgumentException If the rounding mode is invalid.
* @throws RoundingNecessaryException If RoundingMode::UNNECESSARY is provided but rounding is necessary.
*
* @psalm-suppress ImpureFunctionCall
* @param \VendorPrefix\Brick\Math\RoundingMode::* $roundingMode
*/
final public function divRound(string $a, string $b, $roundingMode) : string
{
[$quotient, $remainder] = $this->divQR($a, $b);
$hasDiscardedFraction = ($remainder !== '0');
$isPositiveOrZero = ($a[0] === '-') === ($b[0] === '-');
$discardedFractionSign = function() use ($remainder, $b) : int {
$r = $this->abs($this->mul($remainder, '2'));
$b = $this->abs($b);
return $this->cmp($r, $b);
};
$increment = false;
switch ($roundingMode) {
case RoundingMode::UNNECESSARY:
if ($hasDiscardedFraction) {
throw RoundingNecessaryException::roundingNecessary();
}
break;
case RoundingMode::UP:
$increment = $hasDiscardedFraction;
break;
case RoundingMode::DOWN:
break;
case RoundingMode::CEILING:
$increment = $hasDiscardedFraction && $isPositiveOrZero;
break;
case RoundingMode::FLOOR:
$increment = $hasDiscardedFraction && ! $isPositiveOrZero;
break;
case RoundingMode::HALF_UP:
$increment = $discardedFractionSign() >= 0;
break;
case RoundingMode::HALF_DOWN:
$increment = $discardedFractionSign() > 0;
break;
case RoundingMode::HALF_CEILING:
$increment = $isPositiveOrZero ? $discardedFractionSign() >= 0 : $discardedFractionSign() > 0;
break;
case RoundingMode::HALF_FLOOR:
$increment = $isPositiveOrZero ? $discardedFractionSign() > 0 : $discardedFractionSign() >= 0;
break;
case RoundingMode::HALF_EVEN:
$lastDigit = (int) $quotient[-1];
$lastDigitIsEven = ($lastDigit % 2 === 0);
$increment = $lastDigitIsEven ? $discardedFractionSign() > 0 : $discardedFractionSign() >= 0;
break;
default:
throw new \InvalidArgumentException('Invalid rounding mode.');
}
if ($increment) {
return $this->add($quotient, $isPositiveOrZero ? '1' : '-1');
}
return $quotient;
}
/**
* Calculates bitwise AND of two numbers.
*
* This method can be overridden by the concrete implementation if the underlying library
* has built-in support for bitwise operations.
*/
public function and(string $a, string $b) : string
{
return $this->bitwise('and', $a, $b);
}
/**
* Calculates bitwise OR of two numbers.
*
* This method can be overridden by the concrete implementation if the underlying library
* has built-in support for bitwise operations.
*/
public function or(string $a, string $b) : string
{
return $this->bitwise('or', $a, $b);
}
/**
* Calculates bitwise XOR of two numbers.
*
* This method can be overridden by the concrete implementation if the underlying library
* has built-in support for bitwise operations.
*/
public function xor(string $a, string $b) : string
{
return $this->bitwise('xor', $a, $b);
}
/**
* Performs a bitwise operation on a decimal number.
*
* @param 'and'|'or'|'xor' $operator The operator to use.
* @param string $a The left operand.
* @param string $b The right operand.
*/
private function bitwise(string $operator, string $a, string $b) : string
{
[$aNeg, $bNeg, $aDig, $bDig] = $this->init($a, $b);
$aBin = $this->toBinary($aDig);
$bBin = $this->toBinary($bDig);
$aLen = \strlen($aBin);
$bLen = \strlen($bBin);
if ($aLen > $bLen) {
$bBin = \str_repeat("\x00", $aLen - $bLen) . $bBin;
} elseif ($bLen > $aLen) {
$aBin = \str_repeat("\x00", $bLen - $aLen) . $aBin;
}
if ($aNeg) {
$aBin = $this->twosComplement($aBin);
}
if ($bNeg) {
$bBin = $this->twosComplement($bBin);
}
switch ($operator) {
case 'and':
$value = $aBin & $bBin;
break;
case 'or':
$value = $aBin | $bBin;
break;
case 'xor':
$value = $aBin ^ $bBin;
break;
}
switch ($operator) {
case 'and':
$negative = ($aNeg and $bNeg);
break;
case 'or':
$negative = ($aNeg or $bNeg);
break;
case 'xor':
$negative = ($aNeg xor $bNeg);
break;
}
if ($negative) {
$value = $this->twosComplement($value);
}
$result = $this->toDecimal($value);
return $negative ? $this->neg($result) : $result;
}
/**
* @param string $number A positive, binary number.
*/
private function twosComplement(string $number) : string
{
$xor = \str_repeat("\xff", \strlen($number));
$number ^= $xor;
for ($i = \strlen($number) - 1; $i >= 0; $i--) {
$byte = \ord($number[$i]);
if (++$byte !== 256) {
$number[$i] = \chr($byte);
break;
}
$number[$i] = "\x00";
if ($i === 0) {
$number = "\x01" . $number;
}
}
return $number;
}
/**
* Converts a decimal number to a binary string.
*
* @param string $number The number to convert, positive or zero, only digits.
*/
private function toBinary(string $number) : string
{
$result = '';
while ($number !== '0') {
[$number, $remainder] = $this->divQR($number, '256');
$result .= \chr((int) $remainder);
}
return \strrev($result);
}
/**
* Returns the positive decimal representation of a binary number.
*
* @param string $bytes The bytes representing the number.
*/
private function toDecimal(string $bytes) : string
{
$result = '0';
$power = '1';
for ($i = \strlen($bytes) - 1; $i >= 0; $i--) {
$index = \ord($bytes[$i]);
if ($index !== 0) {
$result = $this->add($result, ($index === 1)
? $power
: $this->mul($power, (string) $index)
);
}
if ($i !== 0) {
$power = $this->mul($power, '256');
}
}
return $result;
}
}
@@ -0,0 +1,65 @@
<?php
declare(strict_types=1);
namespace VendorPrefix\Brick\Math\Internal\Calculator;
use VendorPrefix\Brick\Math\Internal\Calculator;
/**
* Calculator implementation built around the bcmath library.
*
* @internal
*
* @psalm-immutable
*/
class BcMathCalculator extends Calculator
{
public function add(string $a, string $b) : string
{
return \bcadd($a, $b, 0);
}
public function sub(string $a, string $b) : string
{
return \bcsub($a, $b, 0);
}
public function mul(string $a, string $b) : string
{
return \bcmul($a, $b, 0);
}
public function divQ(string $a, string $b) : string
{
return \bcdiv($a, $b, 0);
}
public function divR(string $a, string $b) : string
{
return \bcmod($a, $b, 0);
}
public function divQR(string $a, string $b) : array
{
$q = \bcdiv($a, $b, 0);
$r = \bcmod($a, $b, 0);
return [$q, $r];
}
public function pow(string $a, int $e) : string
{
return \bcpow($a, (string) $e, 0);
}
public function modPow(string $base, string $exp, string $mod) : string
{
return \bcpowmod($base, $exp, $mod, 0);
}
public function sqrt(string $n) : string
{
return \bcsqrt($n, 0);
}
}
@@ -0,0 +1,108 @@
<?php
declare(strict_types=1);
namespace VendorPrefix\Brick\Math\Internal\Calculator;
use VendorPrefix\Brick\Math\Internal\Calculator;
/**
* Calculator implementation built around the GMP library.
*
* @internal
*
* @psalm-immutable
*/
class GmpCalculator extends Calculator
{
public function add(string $a, string $b) : string
{
return \gmp_strval(\gmp_add($a, $b));
}
public function sub(string $a, string $b) : string
{
return \gmp_strval(\gmp_sub($a, $b));
}
public function mul(string $a, string $b) : string
{
return \gmp_strval(\gmp_mul($a, $b));
}
public function divQ(string $a, string $b) : string
{
return \gmp_strval(\gmp_div_q($a, $b));
}
public function divR(string $a, string $b) : string
{
return \gmp_strval(\gmp_div_r($a, $b));
}
public function divQR(string $a, string $b) : array
{
[$q, $r] = \gmp_div_qr($a, $b);
return [
\gmp_strval($q),
\gmp_strval($r)
];
}
public function pow(string $a, int $e) : string
{
return \gmp_strval(\gmp_pow($a, $e));
}
public function modInverse(string $x, string $m) : ?string
{
$result = \gmp_invert($x, $m);
if ($result === false) {
return null;
}
return \gmp_strval($result);
}
public function modPow(string $base, string $exp, string $mod) : string
{
return \gmp_strval(\gmp_powm($base, $exp, $mod));
}
public function gcd(string $a, string $b) : string
{
return \gmp_strval(\gmp_gcd($a, $b));
}
public function fromBase(string $number, int $base) : string
{
return \gmp_strval(\gmp_init($number, $base));
}
public function toBase(string $number, int $base) : string
{
return \gmp_strval($number, $base);
}
public function and(string $a, string $b) : string
{
return \gmp_strval(\gmp_and($a, $b));
}
public function or(string $a, string $b) : string
{
return \gmp_strval(\gmp_or($a, $b));
}
public function xor(string $a, string $b) : string
{
return \gmp_strval(\gmp_xor($a, $b));
}
public function sqrt(string $n) : string
{
return \gmp_strval(\gmp_sqrt($n));
}
}
@@ -0,0 +1,579 @@
<?php
declare(strict_types=1);
namespace VendorPrefix\Brick\Math\Internal\Calculator;
use VendorPrefix\Brick\Math\Internal\Calculator;
/**
* Calculator implementation using only native PHP code.
*
* @internal
*
* @psalm-immutable
*/
class NativeCalculator extends Calculator
{
/**
* The max number of digits the platform can natively add, subtract, multiply or divide without overflow.
* For multiplication, this represents the max sum of the lengths of both operands.
*
* In addition, it is assumed that an extra digit can hold a carry (1) without overflowing.
* Example: 32-bit: max number 1,999,999,999 (9 digits + carry)
* 64-bit: max number 1,999,999,999,999,999,999 (18 digits + carry)
* @readonly
* @var int
*/
private $maxDigits;
/**
* @codeCoverageIgnore
*/
public function __construct()
{
switch (PHP_INT_SIZE) {
case 4:
$this->maxDigits = 9;
break;
case 8:
$this->maxDigits = 18;
break;
default:
throw new \RuntimeException('The platform is not 32-bit or 64-bit as expected.');
}
}
public function add(string $a, string $b) : string
{
/**
* @psalm-var numeric-string $a
* @psalm-var numeric-string $b
*/
$result = $a + $b;
if (is_int($result)) {
return (string) $result;
}
if ($a === '0') {
return $b;
}
if ($b === '0') {
return $a;
}
[$aNeg, $bNeg, $aDig, $bDig] = $this->init($a, $b);
$result = $aNeg === $bNeg ? $this->doAdd($aDig, $bDig) : $this->doSub($aDig, $bDig);
if ($aNeg) {
$result = $this->neg($result);
}
return $result;
}
public function sub(string $a, string $b) : string
{
return $this->add($a, $this->neg($b));
}
public function mul(string $a, string $b) : string
{
/**
* @psalm-var numeric-string $a
* @psalm-var numeric-string $b
*/
$result = $a * $b;
if (is_int($result)) {
return (string) $result;
}
if ($a === '0' || $b === '0') {
return '0';
}
if ($a === '1') {
return $b;
}
if ($b === '1') {
return $a;
}
if ($a === '-1') {
return $this->neg($b);
}
if ($b === '-1') {
return $this->neg($a);
}
[$aNeg, $bNeg, $aDig, $bDig] = $this->init($a, $b);
$result = $this->doMul($aDig, $bDig);
if ($aNeg !== $bNeg) {
$result = $this->neg($result);
}
return $result;
}
public function divQ(string $a, string $b) : string
{
return $this->divQR($a, $b)[0];
}
public function divR(string $a, string $b): string
{
return $this->divQR($a, $b)[1];
}
public function divQR(string $a, string $b) : array
{
if ($a === '0') {
return ['0', '0'];
}
if ($a === $b) {
return ['1', '0'];
}
if ($b === '1') {
return [$a, '0'];
}
if ($b === '-1') {
return [$this->neg($a), '0'];
}
/** @psalm-var numeric-string $a */
$na = $a * 1; // cast to number
if (is_int($na)) {
/** @psalm-var numeric-string $b */
$nb = $b * 1;
if (is_int($nb)) {
// the only division that may overflow is PHP_INT_MIN / -1,
// which cannot happen here as we've already handled a divisor of -1 above.
$q = intdiv($na, $nb);
$r = $na % $nb;
return [
(string) $q,
(string) $r
];
}
}
[$aNeg, $bNeg, $aDig, $bDig] = $this->init($a, $b);
[$q, $r] = $this->doDiv($aDig, $bDig);
if ($aNeg !== $bNeg) {
$q = $this->neg($q);
}
if ($aNeg) {
$r = $this->neg($r);
}
return [$q, $r];
}
public function pow(string $a, int $e) : string
{
if ($e === 0) {
return '1';
}
if ($e === 1) {
return $a;
}
$odd = $e % 2;
$e -= $odd;
$aa = $this->mul($a, $a);
/** @psalm-suppress PossiblyInvalidArgument We're sure that $e / 2 is an int now */
$result = $this->pow($aa, $e / 2);
if ($odd === 1) {
$result = $this->mul($result, $a);
}
return $result;
}
/**
* Algorithm from: https://www.geeksforgeeks.org/modular-exponentiation-power-in-modular-arithmetic/
*/
public function modPow(string $base, string $exp, string $mod) : string
{
// special case: the algorithm below fails with 0 power 0 mod 1 (returns 1 instead of 0)
if ($base === '0' && $exp === '0' && $mod === '1') {
return '0';
}
// special case: the algorithm below fails with power 0 mod 1 (returns 1 instead of 0)
if ($exp === '0' && $mod === '1') {
return '0';
}
$x = $base;
$res = '1';
// numbers are positive, so we can use remainder instead of modulo
$x = $this->divR($x, $mod);
while ($exp !== '0') {
if (in_array($exp[-1], ['1', '3', '5', '7', '9'])) { // odd
$res = $this->divR($this->mul($res, $x), $mod);
}
$exp = $this->divQ($exp, '2');
$x = $this->divR($this->mul($x, $x), $mod);
}
return $res;
}
/**
* Adapted from https://cp-algorithms.com/num_methods/roots_newton.html
*/
public function sqrt(string $n) : string
{
if ($n === '0') {
return '0';
}
// initial approximation
$x = \str_repeat('9', \intdiv(\strlen($n), 2) ?: 1);
$decreased = false;
for (;;) {
$nx = $this->divQ($this->add($x, $this->divQ($n, $x)), '2');
if ($x === $nx || $this->cmp($nx, $x) > 0 && $decreased) {
break;
}
$decreased = $this->cmp($nx, $x) < 0;
$x = $nx;
}
return $x;
}
/**
* Performs the addition of two non-signed large integers.
*/
private function doAdd(string $a, string $b) : string
{
[$a, $b, $length] = $this->pad($a, $b);
$carry = 0;
$result = '';
for ($i = $length - $this->maxDigits;; $i -= $this->maxDigits) {
$blockLength = $this->maxDigits;
if ($i < 0) {
$blockLength += $i;
/** @psalm-suppress LoopInvalidation */
$i = 0;
}
/** @psalm-var numeric-string $blockA */
$blockA = \substr($a, $i, $blockLength);
/** @psalm-var numeric-string $blockB */
$blockB = \substr($b, $i, $blockLength);
$sum = (string) ($blockA + $blockB + $carry);
$sumLength = \strlen($sum);
if ($sumLength > $blockLength) {
$sum = \substr($sum, 1);
$carry = 1;
} else {
if ($sumLength < $blockLength) {
$sum = \str_repeat('0', $blockLength - $sumLength) . $sum;
}
$carry = 0;
}
$result = $sum . $result;
if ($i === 0) {
break;
}
}
if ($carry === 1) {
$result = '1' . $result;
}
return $result;
}
/**
* Performs the subtraction of two non-signed large integers.
*/
private function doSub(string $a, string $b) : string
{
if ($a === $b) {
return '0';
}
// Ensure that we always subtract to a positive result: biggest minus smallest.
$cmp = $this->doCmp($a, $b);
$invert = ($cmp === -1);
if ($invert) {
$c = $a;
$a = $b;
$b = $c;
}
[$a, $b, $length] = $this->pad($a, $b);
$carry = 0;
$result = '';
$complement = 10 ** $this->maxDigits;
for ($i = $length - $this->maxDigits;; $i -= $this->maxDigits) {
$blockLength = $this->maxDigits;
if ($i < 0) {
$blockLength += $i;
/** @psalm-suppress LoopInvalidation */
$i = 0;
}
/** @psalm-var numeric-string $blockA */
$blockA = \substr($a, $i, $blockLength);
/** @psalm-var numeric-string $blockB */
$blockB = \substr($b, $i, $blockLength);
$sum = $blockA - $blockB - $carry;
if ($sum < 0) {
$sum += $complement;
$carry = 1;
} else {
$carry = 0;
}
$sum = (string) $sum;
$sumLength = \strlen($sum);
if ($sumLength < $blockLength) {
$sum = \str_repeat('0', $blockLength - $sumLength) . $sum;
}
$result = $sum . $result;
if ($i === 0) {
break;
}
}
// Carry cannot be 1 when the loop ends, as a > b
assert($carry === 0);
$result = \ltrim($result, '0');
if ($invert) {
$result = $this->neg($result);
}
return $result;
}
/**
* Performs the multiplication of two non-signed large integers.
*/
private function doMul(string $a, string $b) : string
{
$x = \strlen($a);
$y = \strlen($b);
$maxDigits = \intdiv($this->maxDigits, 2);
$complement = 10 ** $maxDigits;
$result = '0';
for ($i = $x - $maxDigits;; $i -= $maxDigits) {
$blockALength = $maxDigits;
if ($i < 0) {
$blockALength += $i;
/** @psalm-suppress LoopInvalidation */
$i = 0;
}
$blockA = (int) \substr($a, $i, $blockALength);
$line = '';
$carry = 0;
for ($j = $y - $maxDigits;; $j -= $maxDigits) {
$blockBLength = $maxDigits;
if ($j < 0) {
$blockBLength += $j;
/** @psalm-suppress LoopInvalidation */
$j = 0;
}
$blockB = (int) \substr($b, $j, $blockBLength);
$mul = $blockA * $blockB + $carry;
$value = $mul % $complement;
$carry = ($mul - $value) / $complement;
$value = (string) $value;
$value = \str_pad($value, $maxDigits, '0', STR_PAD_LEFT);
$line = $value . $line;
if ($j === 0) {
break;
}
}
if ($carry !== 0) {
$line = $carry . $line;
}
$line = \ltrim($line, '0');
if ($line !== '') {
$line .= \str_repeat('0', $x - $blockALength - $i);
$result = $this->add($result, $line);
}
if ($i === 0) {
break;
}
}
return $result;
}
/**
* Performs the division of two non-signed large integers.
*
* @return string[] The quotient and remainder.
*/
private function doDiv(string $a, string $b) : array
{
$cmp = $this->doCmp($a, $b);
if ($cmp === -1) {
return ['0', $a];
}
$x = \strlen($a);
$y = \strlen($b);
// we now know that a >= b && x >= y
$q = '0'; // quotient
$r = $a; // remainder
$z = $y; // focus length, always $y or $y+1
for (;;) {
$focus = \substr($a, 0, $z);
$cmp = $this->doCmp($focus, $b);
if ($cmp === -1) {
if ($z === $x) { // remainder < dividend
break;
}
$z++;
}
$zeros = \str_repeat('0', $x - $z);
$q = $this->add($q, '1' . $zeros);
$a = $this->sub($a, $b . $zeros);
$r = $a;
if ($r === '0') { // remainder == 0
break;
}
$x = \strlen($a);
if ($x < $y) { // remainder < dividend
break;
}
$z = $y;
}
return [$q, $r];
}
/**
* Compares two non-signed large numbers.
*
* @psalm-return -1|0|1
*/
private function doCmp(string $a, string $b) : int
{
$x = \strlen($a);
$y = \strlen($b);
$cmp = $x <=> $y;
if ($cmp !== 0) {
return $cmp;
}
return \strcmp($a, $b) <=> 0; // enforce -1|0|1
}
/**
* Pads the left of one of the given numbers with zeros if necessary to make both numbers the same length.
*
* The numbers must only consist of digits, without leading minus sign.
*
* @return array{string, string, int}
*/
private function pad(string $a, string $b) : array
{
$x = \strlen($a);
$y = \strlen($b);
if ($x > $y) {
$b = \str_repeat('0', $x - $y) . $b;
return [$a, $b, $x];
}
if ($x < $y) {
$a = \str_repeat('0', $y - $x) . $a;
return [$a, $b, $y];
}
return [$a, $b, $x];
}
}
@@ -0,0 +1,19 @@
<?php
declare(strict_types=1);
namespace VendorPrefix\Brick\Math;
class RoundingMode
{
public const UNNECESSARY = 'unnecessary';
public const UP = 'up';
public const DOWN = 'down';
public const CEILING = 'ceiling';
public const FLOOR = 'floor';
public const HALF_UP = 'half_up';
public const HALF_DOWN = 'half_down';
public const HALF_CEILING = 'half_ceiling';
public const HALF_FLOOR = 'half_floor';
public const HALF_EVEN = 'half_even';
}
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2018 PHP-FIG
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,5 @@
# PSR Event Dispatcher
This repository holds the interfaces related to [PSR-14](http://www.php-fig.org/psr/psr-14/).
Note that this is not an Event Dispatcher implementation of its own. It is merely interfaces that describe the components of an Event Dispatcher. See the specification for more details.
@@ -0,0 +1,30 @@
{
"name": "psr/event-dispatcher",
"description": "Standard interfaces for event handling.",
"type": "library",
"keywords": [
"psr",
"psr-14",
"events"
],
"license": "MIT",
"authors": [
{
"name": "PHP-FIG",
"homepage": "http://www.php-fig.org/"
}
],
"require": {
"php": ">=7.2.0"
},
"autoload": {
"psr-4": {
"VendorPrefix\\Psr\\EventDispatcher\\": "src"
}
},
"extra": {
"branch-alias": {
"dev-master": "1.0.x-dev"
}
}
}
@@ -0,0 +1,21 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Psr\EventDispatcher;
/**
* Defines a dispatcher for events.
*/
interface EventDispatcherInterface {
/**
* Provide all relevant listeners with an event to process.
*
* @param object $event
* The object to process.
*
* @return object
* The Event that was passed, now modified by listeners.
*/
public function dispatch( object $event );
}
@@ -0,0 +1,20 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Psr\EventDispatcher;
/**
* Mapper from an event to the listeners that are applicable to that event.
*/
interface ListenerProviderInterface {
/**
* @param object $event
* An event for which to return the relevant listeners.
*
* @return iterable[callable]
* An iterable (array, iterator, or generator) of callables. Each
* callable MUST be type-compatible with $event.
*/
public function getListenersForEvent( object $event ): iterable;
}
@@ -0,0 +1,26 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Psr\EventDispatcher;
/**
* An Event whose processing may be interrupted when the event has been handled.
*
* A Dispatcher implementation MUST check to determine if an Event
* is marked as stopped after each listener is called. If it is then it should
* return immediately without calling any further Listeners.
*/
interface StoppableEventInterface {
/**
* Is propagation stopped?
*
* This will typically only be used by the Dispatcher to determine if the
* previous listener halted propagation.
*
* @return bool
* True if the Event is complete and no further listeners should be called.
* False to continue calling listeners.
*/
public function isPropagationStopped(): bool;
}
@@ -0,0 +1,19 @@
Copyright (c) 2012 PHP Framework Interoperability Group
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
@@ -0,0 +1,55 @@
# PSR Log
This repository holds all interfaces/classes/traits related to
[PSR-3](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md).
Note that this is not a logger of its own. It is merely an interface that
describes a logger. See the specification for more details.
## Installation
```bash
composer require psr/log
```
## Usage
If you need a logger, you can use the interface like this:
```php
<?php
use VendorPrefix\Psr\Log\LoggerInterface;
class Foo
{
private $logger;
public function __construct(LoggerInterface $logger = null)
{
$this->logger = $logger;
}
public function doSomething()
{
if ($this->logger) {
$this->logger->info('Doing work');
}
try {
$this->doSomethingElse();
} catch (Exception $exception) {
$this->logger->error('Oh no!', array('exception' => $exception));
}
// do something useful
}
}
```
You can then pick one of the implementations of the interface to get a logger.
If you want to implement the interface, you can require this package and
implement `VendorPrefix\Psr\Log\LoggerInterface` in your code. Please read the
[specification text](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md)
for details.
@@ -0,0 +1,30 @@
{
"name": "psr/log",
"description": "Common interface for logging libraries",
"keywords": [
"psr",
"psr-3",
"log"
],
"homepage": "https://github.com/php-fig/log",
"license": "MIT",
"authors": [
{
"name": "PHP-FIG",
"homepage": "https://www.php-fig.org/"
}
],
"require": {
"php": ">=8.0.0"
},
"autoload": {
"psr-4": {
"VendorPrefix\\Psr\\Log\\": "src"
}
},
"extra": {
"branch-alias": {
"dev-master": "3.x-dev"
}
}
}
@@ -0,0 +1,14 @@
<?php
namespace VendorPrefix\Psr\Log;
/**
* This is a simple Logger implementation that other Loggers can inherit from.
*
* It simply delegates all log-level-specific methods to the `log` method to
* reduce boilerplate code that a simple Logger that does the same thing with
* messages regardless of the error level has to implement.
*/
abstract class AbstractLogger implements LoggerInterface {
use LoggerTrait;
}
@@ -0,0 +1,6 @@
<?php
namespace VendorPrefix\Psr\Log;
class InvalidArgumentException extends \InvalidArgumentException {
}
@@ -0,0 +1,17 @@
<?php
namespace VendorPrefix\Psr\Log;
/**
* Describes log levels.
*/
class LogLevel {
const EMERGENCY = 'emergency';
const ALERT = 'alert';
const CRITICAL = 'critical';
const ERROR = 'error';
const WARNING = 'warning';
const NOTICE = 'notice';
const INFO = 'info';
const DEBUG = 'debug';
}
@@ -0,0 +1,13 @@
<?php
namespace VendorPrefix\Psr\Log;
/**
* Describes a logger-aware instance.
*/
interface LoggerAwareInterface {
/**
* Sets a logger instance on the object.
*/
public function setLogger( LoggerInterface $logger ): void;
}
@@ -0,0 +1,21 @@
<?php
namespace VendorPrefix\Psr\Log;
/**
* Basic Implementation of LoggerAwareInterface.
*/
trait LoggerAwareTrait {
/**
* The logger instance.
* @var LoggerInterface|null
*/
protected $logger;
/**
* Sets a logger.
*/
public function setLogger( LoggerInterface $logger ): void {
$this->logger = $logger;
}
}
@@ -0,0 +1,109 @@
<?php
namespace VendorPrefix\Psr\Log;
use Stringable;
/**
* Describes a logger instance.
*
* The message MUST be a string or object implementing __toString().
*
* The message MAY contain placeholders in the form: {foo} where foo
* will be replaced by the context data in key "foo".
*
* The context array can contain arbitrary data. The only assumption that
* can be made by implementors is that if an Exception instance is given
* to produce a stack trace, it MUST be in a key named "exception".
*
* See https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md
* for the full interface specification.
*/
interface LoggerInterface {
/**
* System is unusable.
*
* @param mixed[] $context
* @param string|Stringable $message
*/
public function emergency( $message, array $context = [] ): void;
/**
* Action must be taken immediately.
*
* Example: Entire website down, database unavailable, etc. This should
* trigger the SMS alerts and wake you up.
*
* @param mixed[] $context
* @param string|Stringable $message
*/
public function alert( $message, array $context = [] ): void;
/**
* Critical conditions.
*
* Example: Application component unavailable, unexpected exception.
*
* @param mixed[] $context
* @param string|Stringable $message
*/
public function critical( $message, array $context = [] ): void;
/**
* Runtime errors that do not require immediate action but should typically
* be logged and monitored.
*
* @param mixed[] $context
* @param string|Stringable $message
*/
public function error( $message, array $context = [] ): void;
/**
* Exceptional occurrences that are not errors.
*
* Example: Use of deprecated APIs, poor use of an API, undesirable things
* that are not necessarily wrong.
*
* @param mixed[] $context
* @param string|Stringable $message
*/
public function warning( $message, array $context = [] ): void;
/**
* Normal but significant events.
*
* @param mixed[] $context
* @param string|Stringable $message
*/
public function notice( $message, array $context = [] ): void;
/**
* Interesting events.
*
* Example: User logs in, SQL logs.
*
* @param mixed[] $context
* @param string|Stringable $message
*/
public function info( $message, array $context = [] ): void;
/**
* Detailed debug information.
*
* @param mixed[] $context
* @param string|Stringable $message
*/
public function debug( $message, array $context = [] ): void;
/**
* Logs with an arbitrary level.
*
* @param mixed $level
* @param mixed[] $context
*
* @param string|Stringable $message
*
* @throws InvalidArgumentException
*/
public function log( $level, $message, array $context = [] ): void;
}
@@ -0,0 +1,109 @@
<?php
namespace VendorPrefix\Psr\Log;
use Stringable;
/**
* This is a simple Logger trait that classes unable to extend AbstractLogger
* (because they extend another class, etc) can include.
*
* It simply delegates all log-level-specific methods to the `log` method to
* reduce boilerplate code that a simple Logger that does the same thing with
* messages regardless of the error level has to implement.
*/
trait LoggerTrait {
/**
* System is unusable.
*
* @param string|Stringable $message
*/
public function emergency( $message, array $context = [] ): void {
$this->log( LogLevel::EMERGENCY, $message, $context );
}
/**
* Action must be taken immediately.
*
* Example: Entire website down, database unavailable, etc. This should
* trigger the SMS alerts and wake you up.
*
* @param string|Stringable $message
*/
public function alert( $message, array $context = [] ): void {
$this->log( LogLevel::ALERT, $message, $context );
}
/**
* Critical conditions.
*
* Example: Application component unavailable, unexpected exception.
*
* @param string|Stringable $message
*/
public function critical( $message, array $context = [] ): void {
$this->log( LogLevel::CRITICAL, $message, $context );
}
/**
* Runtime errors that do not require immediate action but should typically
* be logged and monitored.
*
* @param string|Stringable $message
*/
public function error( $message, array $context = [] ): void {
$this->log( LogLevel::ERROR, $message, $context );
}
/**
* Exceptional occurrences that are not errors.
*
* Example: Use of deprecated APIs, poor use of an API, undesirable things
* that are not necessarily wrong.
*
* @param string|Stringable $message
*/
public function warning( $message, array $context = [] ): void {
$this->log( LogLevel::WARNING, $message, $context );
}
/**
* Normal but significant events.
*
* @param string|Stringable $message
*/
public function notice( $message, array $context = [] ): void {
$this->log( LogLevel::NOTICE, $message, $context );
}
/**
* Interesting events.
*
* Example: User logs in, SQL logs.
*
* @param string|Stringable $message
*/
public function info( $message, array $context = [] ): void {
$this->log( LogLevel::INFO, $message, $context );
}
/**
* Detailed debug information.
*
* @param string|Stringable $message
*/
public function debug( $message, array $context = [] ): void {
$this->log( LogLevel::DEBUG, $message, $context );
}
/**
* Logs with an arbitrary level.
*
* @param mixed $level
*
* @param string|Stringable $message
*
* @throws InvalidArgumentException
*/
abstract public function log( $level, $message, array $context = [] ): void;
}
@@ -0,0 +1,28 @@
<?php
namespace VendorPrefix\Psr\Log;
use Stringable;
/**
* This Logger can be used to avoid conditional log calls.
*
* Logging should always be optional, and if no logger is provided to your
* library creating a NullLogger instance to have something to throw logs at
* is a good way to avoid littering your code with `if ($this->logger) { }`
* blocks.
*/
class NullLogger extends AbstractLogger {
/**
* Logs with an arbitrary level.
*
* @param mixed[] $context
*
* @param string|Stringable $message
*
* @throws InvalidArgumentException
*/
public function log( $level, $message, array $context = [] ): void {
// noop
}
}
@@ -0,0 +1,47 @@
# Changelog
## [Unreleased]
## [0.1.5] - 2022-01-10
### Added
- Add `UNICODE_VERSION` constant to `Idna` class that returns a string with the Unicode version of the data files used
### Changed
- Update data files to Unicode 14
- Update PHPStan to 1.0
## [0.1.4] - 2021-02-11
### Added
- Test on PHP 8 release
### Fixed
- Handle the rare possibility that string nomalization can fail
## [0.1.3] - 2020-08-03
### Fixed
- Fix bug with domain names containing a URL delimiter
## [0.1.2] - 2020-07-15
### Added
- Performance improvements
## [0.1.1] - 2020-07-10
### Added
- Performance improvements
- Reduced memory footprint
## [0.1.0] - 2020-06-10
- Initial release
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2020 Trevor Rowbotham
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,350 @@
# IDNA
[![License](https://img.shields.io/github/license/TRowbotham/idna?style=flat-square)](https://github.com/TRowbotham/URL-Parser/blob/master/LICENSE)
[![Build Status](https://img.shields.io/travis/com/TRowbotham/idna/master?style=flat-square)](https://travis-ci.com/github/TRowbotham/idna)
[![Code Coverage](https://img.shields.io/codecov/c/github/TRowbotham/idna/master?style=flat-square)](https://codecov.io/gh/TRowbotham/idna)
[![Version](https://img.shields.io/packagist/v/rowbot/idna?style=flat-square)](https://packagist.org/packages/rowbot/idna)
[![Downloads](https://img.shields.io/packagist/dt/rowbot/idna?style=flat-square)](https://packagist.org/packages/rowbot/idna)
A fully compliant implementation of [UTS#46](https://www.unicode.org/reports/tr46/), otherwise known
as Unicode IDNA Compatibility Processing. You can read more about the differences between IDNA2003,
IDNA2008, and UTS#46 in [Section 7. IDNA Comparison](https://www.unicode.org/reports/tr46/#IDNAComparison)
of the specification.
This library currently ships with Unicode 14.0.0 support and implements Version 14.0.0, Revision 27 of IDNA Compatibility
Processing. It has the ability to use Unicode 11.0.0 to Unicode 14.0.0. While this library likely supports versions of
Unicode less than 11.0.0, the format of the Unicode test files were changed beginning in 11.0.0 and as a result, versions
of Unicode less than 11.0.0 have not been tested.
- [Requirements](#requirements)
- [Installation](#installation)
- [API](#api)
- [Error Codes](#error-codes)
- [The WTFs of Unicode Support in PHP](#the-wtfs-of-unicode-support-in-php)
- [FAQs](#faqs)
- [Internals](#internals)
## Requirements
- PHP 7.1+
- `rowbot/punycode`
- `symfony/polyfill-intl-normalizer`
## Installation
```bash
composer require rowbot/idna
```
## API
### Idna::UNICODE_VERSION
The Unicode version of the data files used, as a string.
### Idna::toAscii(string $domain, array $options = []): IdnaResult
Converts a domain name to its ASCII form. Anytime an error is recorded while doing an ASCII
transformation, the transformation is considered to have failed and whatever domain name string is
returned is considered "garbage". What you do with that result is entirely up to you.
#### toAscii Parameters
- $domain - A domain name to convert to ASCII.
- $options - An array of options for customizing the behavior of the transformation. Possible
options include:
- `"CheckBidi"` - Checks the domain name string for errors with bi-directional characters.
Defaults to true.
- `"CheckHyphens"` - Checks the domain name string for the positioning of hypens. Defaults to
true.
- `"CheckJoiners"` - Checks the domain name string for errors with joining code points. Defaults
to true.
- `"UseSTD3ASCIIRules"` - Disallows the use of ASCII characters other than `[a-zA-Z0-9-]`.
Defaults to true.
- `"Transitional_Processing"` - Whether transitional or non-transitional processing is used. When
enabled, processing behaves more like IDNA2003 and when disabled behaves like IDNA2008. Defaults
to false, which means that non-transitional processing is used by default.
- `"VerifyDnsLength"` - Validates the length of the domain name string and it's individual labels.
Defaults to true.
**Note**: All options are case-sensitive.
```php
use VendorPrefix\Rowbot\Idna\Idna;
$result = Idna::toAscii('x-.xn--nxa');
// You must not use an ASCII domain that has errors.
if ($result->hasErrors()) {
throw new \Exception();
}
echo $result->getDomain(); // x-.xn--nxa
```
### Idna::toUnicode(string $domain, array $options = []): IdnaResult
Converts the domain name to its Unicode form. Unlike the toAscii transformation, toUnicode does not
have a failure concept. This means that you can always use the returned string. However, deciding
what to do with the returned domain name string when an error is recorded is entirely up to you.
- $domain - A domain name to convert to UTF-8.
- $options - An array of options for customizing the behavior of the transformation. Possible
options include:
- `"CheckBidi"` - Checks the domain name string for errors with bi-directional characters.
Defaults to true.
- `"CheckHyphens"` - Checks the domain name string for the positioning of hypens. Defaults to
true.
- `"CheckJoiners"` - Checks the domain name string for errors with joining code points. Defaults
to true.
- `"UseSTD3ASCIIRules"` - Disallows the use of ASCII characters other than `[a-zA-Z0-9-]`.
Defaults to true.
- `"Transitional_Processing"` - Whether transitional or non-transitional processing is used. When
enabled, processing behaves more like IDNA2003 and when disabled behaves like IDNA2008. Defaults
to false, which means that non-transitional processing is used by default.
**Note**: All options are case-sensitive.
**Note**: `"VerifyDnsLength"` is not a valid option here.
```php
use VendorPrefix\Rowbot\Idna\Idna;
$result = Idna::toUnicode('xn---with-SUPER-MONKEYS-pc58ag80a8qai00g7n9n.com');
echo $result->getDomain(); // 安室奈美恵-with-super-monkeys.com
```
### IdnaResult object
#### Members
##### IdnaResult::getDomain(): string
Returns the transformed domain name string.
##### IdnaResult::getErrors(): int
Returns a bitmask representing all errors that were recorded while processing the input domain name
string.
##### IdnaResult::hasError(int $error): bool
Returns whether or not a specific error was recorded.
##### IdnaResult::hasErrors(): bool
Returns whether or not an error was recorded while processing the input domain name string.
##### IdnaResult::isTransitionalDifferent(): bool
Returns `true` if the input domain name contains a code point that has a status of `"deviation"`.
This status indicates that the code points are handled differently in IDNA2003 than they are in
IDNA2008. At the time of writing, there are only 4 code points that have this status. They are
U+00DF, U+03C2, U+200C, and U+200D.
## Error Codes
- `Idna::ERROR_EMPTY_LABEL`
The domain name or one of it's labels are an empty string.
- `Idna::ERROR_LABEL_TOO_LONG`
One of the domain's labels exceeds 63 bytes.
- `Idna::ERROR_DOMAIN_NAME_TOO_LONG`
The length of the domain name exceeds 253 bytes.
- `Idna::ERROR_LEADING_HYPHEN`
One of the domain name's labels starts with a hyphen-minus character (-).
- `Idna::ERROR_TRAILING_HYPHEN`
One of the domain name's labels ends with a hyphen-minus character (-).
- `Idna::ERROR_HYPHEN_3_4`
One of the domain name's labels contains a hyphen-minus character in the 3rd and 4th position.
- `Idna::ERROR_LEADING_COMBINING_MARK`
One of the domain name's labels starts with a combining mark.
- `Idna::ERROR_DISALLOWED`
The domain name contains characters that are disallowed.
- `Idna::ERROR_PUNYCODE`
One of the domain name's labels starts with "xn--", but is not valid punycode.
- `Idna::ERROR_LABEL_HAS_DOT`
One of the domain name's labels contains a full stop character (.).
- `Idna::ERROR_INVALID_ACE_LABEL`
One of the domain name's labels is an invalid ACE label.
- `Idna::ERROR_BIDI`
The domain name does not meet the BiDi requirements for IDNA.
- `Idna::ERROR_CONTEXTJ`
One of the domain name's labels does not meet the CONTEXTJ requirements for IDNA.
## The WTFs of Unicode Support in PHP
In any given version of PHP, there can be a multitude of different versions of Unicode in use.
So... WTF?
- What does this mean?
This means that if I ask the same question, each of the extensions listed below can give me a
different answer. This is compounded by the fact that the versions of Unicode used in the below
extensions can also be different given the same version of PHP. For example, the `intl` extension
being used by my installation of PHP 7.2 could be using Unicode version 11, but the `intl`
extension in your web hosts installation of PHP 7.2 could be using Unicode version 6.
- How does this happen?
- The `mbstring` extension uses its own version of Unicode.
- The `Onigurama` library, which is behind `mbstring`'s regular expression functions, uses its
own version of Unicode.
- The `PCRE` extension, which is the primary extension for working with regular extensions in
PHP, uses its own version of Unicode.
- The `intl` extension uses its own version of Unicode.
- Any other extensions that add their own versions of Unicode.
- Userland libraries use their own version of Unicode (including this library).
- This library
Being able to use `mbstring` or `intl` extensions would be helpful, but we cannot depend on them
being installed or them having a consistent version of Unicode when they are installed.
Additionally, extensions like `PCRE` could be compiled without Unicode support entirely, though we
do rely on `PCRE`'s `u` modifier. For this reason we have to include our own Unicode data.
## FAQs
- **I'm confused! Is this IDNA2003 or IDNA2008?**
The answer to this is somewhat convoluted. TL;DR; It is neither.
Here is what the spec says:
> To satisfy user expectations for mapping, and provide maximal compatibility with IDNA2003, this
> document specifies a mapping for use with IDNA2008. In addition, to transition more smoothly to
> IDNA2008, this document provides a Unicode algorithm for a standardized processing that allows
> conformant implementations to minimize the security and interoperability problems caused by the
> differences between IDNA2003 and IDNA2008. This Unicode IDNA Compatibility Processing is
> structured according to IDNA2003 principles, but extends those principles to Unicode 5.2 and
> later. It also incorporates the repertoire extensions provided by IDNA2008.
More information can be found in [Section 2. Unicode IDNA Compatibility Processing](https://www.unicode.org/reports/tr46/#Compatibility_Processing)
and [Section 7. IDNA Comparison](https://www.unicode.org/reports/tr46/#IDNAComparison).
- **What are the recommended options?**
The default options are the recommended options, which are also the strictest.
```php
// Default options.
[
'CheckHyphens' => true,
'CheckBidi' => true,
'CheckJoiners' => true,
'UseSTD3ASCIIRules' => true,
'Transitional_Processing' => false,
'VerifyDnsLength' => true, // Only for Idna::toAscii()
];
```
- **Do I have to provide all the options?**
No. You only need to specifiy the options that you wish to change. Any option you specify will
overwrite the default options.
```php
use VendorPrefix\Rowbot\Idna\Idna;
$result = Idna::toAscii('x-.xn--nxa', ['CheckHyphens' => true]);
$result->hasErrors(); // true
$result->hasError(Idna::ERROR_TRAILING_HYPHEN); // true
$result = Idna::toAscii('x-.xn--nxa', ['CheckHyphens' => false]);
$result->hasErrors(); // false
$result->hasError(Idna::ERROR_TRAILING_HYPHEN); // false
```
- **What is the difference between `Transitional` and `Non-transitional` processing?**
`Transitional` processing is designed to mimic IDNA2003. It is highly recommended to use
`Non-transitional` processing, which tries to mimic IDNA2008. You can always check if a domain
name would be different between the two processing modes by checking
`IdnaResult::isTransitionalDifferent()`.
- **Wouldn't it be neat if you also tested against the `idn_to_ascii()` and `idn_to_utf8()`
functions from the `intl` extension?**
Yes. Yes, it would be neat if we could do an additional check for parity with the ICU
implementation, however, for the reasons outlined above in
[The WTFs of Unicode Support in PHP](#the-wtfs-of-unicode-support-in-php), testing against these
functions would be unreliable at best.
- **Why does the `intl` extension show weird characters that look like diamonds with question marks
inside in invalid domains, but your implementation doesn't?**
```php
$input = '憡?Ⴔ.XN--1UG73GL146A';
idn_to_utf8($input, 0, IDNA_INTL_VARIANT_UTS46, $info);
echo $info['result']; // 憡��.xn--1ug73gl146a�
echo ($info['errors'] & IDNA_ERROR_DISALLOWED) !== 0; // true
$result = \VendorPrefix\Rowbot\Idna\Idna::toUnicode($input);
echo $result->getDomain(); // 憡?Ⴔ.xn--1ug73gl146a
echo $result->hasError(\VendorPrefix\Rowbot\Idna\Idna::ERROR_DISALLOWED); // true
```
From [Section 4. Processing](https://www.unicode.org/reports/tr46/#Processing):
> Implementations may make further modifications to the resulting Unicode string when showing it to
> the user. For example, it is recommended that disallowed characters be replaced by a U+FFFD to
> make them visible to the user. Similarly, labels that fail processing during steps 4 or 5 may be
> marked by the insertion of a U+FFFD or other visual device.
This implementation currently does not make these recommended modifications.
## Internals
### Building
Unicode data files are fetched from https://www.unicode.org/Public. Currently, Unicode version
11.0.0-14.0.0 are supported. To change the version of Unicode that the library is built with, you
must first change the value of the `\VendorPrefix\Rowbot\Idna::UNICODE_VERSION` constant, like so:
```diff
class Idna
{
- public const UNICODE_VERSION = '13.0.0';
+ public const UNICODE_VERSION = '14.0.0';
```
Then to generate the necessary data files, you execute the following command:
```bash
php bin/generateDataFiles.php
```
If no assertions or exceptions have occured, then you have successfully changed the Unicode version.
You should now execute the tests to make sure everything is good to go. The tests will automatically
fetch the version appropriate tests as the test files are not generated by the above command.
```bash
vendor/bin/phpunit
```
@@ -0,0 +1,85 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Rowbot\Idna\Bin;
use VendorPrefix\Rowbot\Idna\Idna;
use RuntimeException;
use function array_map;
use function explode;
use function fclose;
use function fopen;
use function intval;
use function sprintf;
use function usort;
abstract class Builder {
protected const BASE_URL = 'https://www.unicode.org/Public';
/**
* @return resource
*/
protected static function getIdnaDataResource( string $file ) {
$file = sprintf( '%s/idna/%s/%s', self::BASE_URL, Idna::UNICODE_VERSION, $file );
$handle = fopen( $file, 'r' );
if ( $handle === false ) {
throw new RuntimeException( 'Failed to open ' . $file );
}
return $handle;
}
/**
* @return resource
*/
protected static function getUnicodeDataResource( string $file ) {
$file = sprintf( '%s/%s/ucd/%s', self::BASE_URL, Idna::UNICODE_VERSION, $file );
$handle = fopen( $file, 'r' );
if ( $handle === false ) {
throw new RuntimeException( 'Failed to open ' . $file );
}
return $handle;
}
/**
* @return list<int>
*/
protected static function parseCodePoints( string $codePoints ): array {
$range = explode( '..', $codePoints );
$start = intval( $range[0], 16 );
$end = isset( $range[1] ) ? intval( $range[1], 16 ) : $start;
return [ $start, $end ];
}
/**
* @return array<int, array<int, array<int, int>|string>>
*/
protected static function parseProperties( string $file ): array {
$handle = self::getUnicodeDataResource( $file );
$retVal = [];
while ( ( $line = fgets( $handle ) ) !== false ) {
if ( $line === "\n" || $line[0] === '#' ) {
continue;
}
[ $data ] = explode( '#', $line );
$data = array_map( 'trim', explode( ';', $data ) );
$data[0] = self::parseCodePoints( $data[0] );
$retVal[] = $data;
}
fclose( $handle );
usort( $retVal, static function ( array $a, array $b ): int {
return $a[0][0] <=> $b[0][0];
} );
return $retVal;
}
}
@@ -0,0 +1,129 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Rowbot\Idna\Bin;
use VendorPrefix\Rowbot\Idna\CodePoint;
use RuntimeException;
use function array_map;
use function explode;
use function fclose;
use function fgets;
use function file_put_contents;
use function intval;
use function preg_match_all;
use const DIRECTORY_SEPARATOR as DS;
class IdnaDataBuilder extends Builder {
public static function buildHashMaps( string $output ): void {
$handle = self::getIdnaDataResource( 'IdnaMappingTable.txt' );
$statuses = [
'mapped' => [],
'ignored' => [],
'deviation' => [],
'disallowed' => [],
'disallowed_STD3_mapped' => [],
'disallowed_STD3_valid' => [],
];
$rangeFallback = '';
while ( ( $line = fgets( $handle ) ) !== false ) {
if ( $line === "\n" || $line[0] === '#' ) {
continue;
}
[ $data ] = explode( '#', $line );
$data = array_map( 'trim', explode( ';', $data ) );
[ $codePoints, $status ] = $data;
$codePoints = self::parseCodePoints( $codePoints );
$diff = $codePoints[1] - $codePoints[0] + 1;
switch ( $status ) {
case 'valid':
// skip valid.
break;
case 'mapped':
case 'deviation':
case 'disallowed_STD3_mapped':
if ( preg_match_all( '/[[:xdigit:]]+/', $data[2], $matches ) === false ) {
throw new RuntimeException();
}
$mapped = '';
foreach ( $matches[0] as $codePoint ) {
$mapped .= CodePoint::encode( intval( $codePoint, 16 ) );
}
for ( $i = 0; $i < $diff; ++ $i ) {
$statuses[ $status ][ $codePoints[0] + $i ] = $mapped;
}
break;
case 'disallowed':
if ( $diff > 30 ) {
if ( $rangeFallback !== '' ) {
$rangeFallback .= "\n\n";
}
$rangeFallback .= <<<RANGE_FALLBACK
if (\$codePoint >= {$codePoints[0]} && \$codePoint <= {$codePoints[1]}) {
return true;
}
RANGE_FALLBACK;
continue 2;
}
for ( $i = 0; $i < $diff; ++ $i ) {
$statuses[ $status ][ $codePoints[0] + $i ] = true;
}
break;
case 'ignored':
case 'disallowed_STD3_valid':
for ( $i = 0; $i < $diff; ++ $i ) {
$statuses[ $status ][ $codePoints[0] + $i ] = true;
}
break;
}
}
fclose( $handle );
file_put_contents( $output . DS . 'mapped.php', "<?php\n\nreturn " . var_export( $statuses['mapped'], true ) . ";\n" );
file_put_contents( $output . DS . 'ignored.php', "<?php\n\nreturn " . var_export( $statuses['ignored'], true ) . ";\n" );
file_put_contents( $output . DS . 'deviation.php', "<?php\n\nreturn " . var_export( $statuses['deviation'], true ) . ";\n" );
file_put_contents( $output . DS . 'disallowed.php', "<?php\n\nreturn " . var_export( $statuses['disallowed'], true ) . ";\n" );
file_put_contents( $output . DS . 'disallowed_STD3_mapped.php',
"<?php\n\nreturn " . var_export( $statuses['disallowed_STD3_mapped'], true ) . ";\n" );
file_put_contents( $output . DS . 'disallowed_STD3_valid.php',
"<?php\n\nreturn " . var_export( $statuses['disallowed_STD3_valid'], true ) . ";\n" );
$s = <<<CP_STATUS
<?php
declare(strict_types=1);
namespace VendorPrefix\Rowbot\Idna\Resource;
final class DisallowedRanges
{
public static function inRange(int \$codePoint): bool
{
{$rangeFallback}
return false;
}
}
CP_STATUS;
file_put_contents( $output . DS . 'DisallowedRanges.php', $s );
}
}
@@ -0,0 +1,204 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Rowbot\Idna\Bin;
use function array_filter;
use function assert;
use function file_put_contents;
use function in_array;
use function is_array;
use function sprintf;
use const DIRECTORY_SEPARATOR as DS;
class RegexBuilder extends Builder {
public static function buildRegexClass( string $output ): void {
$bidiData = self::parseProperties( 'extracted/DerivedBidiClass.txt' );
$rtlLabel = sprintf(
'/[%s]/u',
self::buildCharacterClass( array_filter( $bidiData, static function ( array $data ): bool {
return in_array( $data[1], [ 'R', 'AL', 'AN' ], true );
} ) )
);
// Step 1. The first character must be a character with Bidi property L, R, or AL. If it has the R
// or AL property, it is an RTL label; if it has the L property, it is an LTR label.
//
// Because any code point not explicitly listed in DerivedBidiClass.txt is considered to have the
// 'L' property, we negate a character class matching all code points explicitly listed in
// DerivedBidiClass.txt minus the ones explicitly marked as 'L'.
$bidiStep1Ltr = sprintf(
'/^[^%s]/u',
self::buildCharacterClass( array_filter( $bidiData, static function ( array $data ): bool {
return $data[1] !== 'L';
} ) )
);
$bidiStep1Rtl = sprintf(
'/^[%s]/u',
self::buildCharacterClass( array_filter( $bidiData, static function ( array $data ): bool {
return in_array( $data[1], [ 'R', 'AL' ], true );
} ) )
);
// Step 2. In an RTL label, only characters with the Bidi properties R, AL, AN, EN, ES, CS, ET, ON,
// BN, or NSM are allowed.
$bidiStep2 = sprintf(
'/[^%s]/u',
self::buildCharacterClass( array_filter( $bidiData, static function ( array $data ): bool {
return in_array( $data[1], [ 'R', 'AL', 'AN', 'EN', 'ES', 'CS', 'ET', 'ON', 'BN', 'NSM' ], true );
} ) )
);
// Step 3. In an RTL label, the end of the label must be a character with Bidi property R, AL, EN,
// or AN, followed by zero or more characters with Bidi property NSM.
$bidiStep3 = sprintf(
'/[%s][%s]*$/u',
self::buildCharacterClass( array_filter( $bidiData, static function ( array $data ): bool {
return in_array( $data[1], [ 'R', 'AL', 'EN', 'AN' ], true );
} ) ),
self::buildCharacterClass( array_filter( $bidiData, static function ( array $data ): bool {
return $data[1] === 'NSM';
} ) )
);
// Step 4. In an RTL label, if an EN is present, no AN may be present, and vice versa.
$bidiStep4EN = sprintf(
'/[%s]/u',
self::buildCharacterClass( array_filter( $bidiData, static function ( array $data ): bool {
return $data[1] === 'EN';
} ) )
);
$bidiStep4AN = sprintf(
'/[%s]/u',
self::buildCharacterClass( array_filter( $bidiData, static function ( array $data ): bool {
return $data[1] === 'AN';
} ) )
);
// Step 5. In an LTR label, only characters with the Bidi properties L, EN, ES, CS, ET, ON, BN, or
// NSM are allowed.
//
// Because any code point not explicitly listed in DerivedBidiClass.txt is considered to have the
// 'L' property, we create a character class matching all code points explicitly listed in
// DerivedBidiClass.txt minus the ones explicitly marked as 'L', 'EN', 'ES', 'CS', 'ET', 'ON',
// 'BN', or 'NSM'.
$bidiStep5 = sprintf(
'/[%s]/u',
self::buildCharacterClass( array_filter( $bidiData, static function ( array $data ): bool {
return ! in_array( $data[1], [ 'L', 'EN', 'ES', 'CS', 'ET', 'ON', 'BN', 'NSM' ], true );
} ) )
);
// Step 6. In an LTR label, the end of the label must be a character with Bidi property L or EN,
// followed by zero or more characters with Bidi property NSM.
//
// Again, because any code point not explicitly listed in DerivedBidiClass.txt is considered to
// have the 'L' property, we negate a character class matching all code points explicitly listed in
// DerivedBidiClass.txt to match characters with the 'L' and 'EN' property.
$bidiStep6 = sprintf(
'/[^%s][%s]*$/u',
self::buildCharacterClass( array_filter( $bidiData, static function ( array $data ): bool {
return ! in_array( $data[1], [ 'L', 'EN' ], true );
} ) ),
self::buildCharacterClass( array_filter( $bidiData, static function ( array $data ): bool {
return $data[1] === 'NSM';
} ) )
);
$combiningMarks = self::buildCombiningMarksRegex();
$zwnj = self::buildJoiningTypesRegex();
$s = <<<RegexClass
<?php
// This file was auto generated by running 'php bin/generateDataFiles.php'
declare(strict_types=1);
namespace VendorPrefix\Rowbot\Idna\Resource;
final class Regex
{
public const COMBINING_MARK = '{$combiningMarks}';
public const RTL_LABEL = '{$rtlLabel}';
public const BIDI_STEP_1_LTR = '{$bidiStep1Ltr}';
public const BIDI_STEP_1_RTL = '{$bidiStep1Rtl}';
public const BIDI_STEP_2 = '{$bidiStep2}';
public const BIDI_STEP_3 = '{$bidiStep3}';
public const BIDI_STEP_4_AN = '{$bidiStep4AN}';
public const BIDI_STEP_4_EN = '{$bidiStep4EN}';
public const BIDI_STEP_5 = '{$bidiStep5}';
public const BIDI_STEP_6 = '{$bidiStep6}';
public const ZWNJ = '{$zwnj}';
/**
* @codeCoverageIgnore
*/
private function __construct()
{
}
}
RegexClass;
file_put_contents( $output . DS . 'Regex.php', $s );
}
private static function buildJoiningTypesRegex(): string {
$joiningTypes = self::parseProperties( 'extracted/DerivedJoiningType.txt' );
// ((Joining_Type:{L,D})(Joining_Type:T)*\u200C(Joining_Type:T)*(Joining_Type:{R,D}))
// We use a capturing group around the first portion of the regex so we can count the byte length
// of the match and increment preg_match's offset accordingly.
return sprintf(
'/([%1$s%2$s][%3$s]*\x{200C}[%3$s]*)[%4$s%2$s]/u',
self::buildCharacterClass( array_filter( $joiningTypes, static function ( array $data ): bool {
return $data[1] === 'L';
} ) ),
self::buildCharacterClass( array_filter( $joiningTypes, static function ( array $data ): bool {
return $data[1] === 'D';
} ) ),
self::buildCharacterClass( array_filter( $joiningTypes, static function ( array $data ): bool {
return $data[1] === 'T';
} ) ),
self::buildCharacterClass( array_filter( $joiningTypes, static function ( array $data ): bool {
return $data[1] === 'R';
} ) )
);
}
private static function buildCombiningMarksRegex(): string {
$generalCategories = self::parseProperties( 'extracted/DerivedGeneralCategory.txt' );
return sprintf(
'/^[%s]/u',
self::buildCharacterClass( array_filter( $generalCategories, static function ( array $data ): bool {
return in_array( $data[1], [ 'Mc', 'Me', 'Mn' ], true );
} ) )
);
}
/**
* @param array<int, array<int, array<int, int>|string>> $data
*/
private static function buildCharacterClass( array $data ): string {
$out = '';
foreach ( $data as $codePoints ) {
assert( is_array( $codePoints[0] ) );
if ( $codePoints[0][0] !== $codePoints[0][1] ) {
$out .= sprintf( '\x{%04X}-\x{%04X}', ...$codePoints[0] );
continue;
}
$out .= sprintf( '\x{%04X}', $codePoints[0][0] );
}
return $out;
}
}
@@ -0,0 +1,45 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Rowbot\Idna\Bin;
use function array_map;
use function explode;
use function fclose;
use function fgets;
use function file_put_contents;
use function var_export;
use const DIRECTORY_SEPARATOR as DS;
class ViramaDataBuilder extends Builder {
public static function buildHashMap( string $output ): void {
$handle = self::getUnicodeDataResource( 'extracted/DerivedCombiningClass.txt' );
$virama = [];
while ( ( $line = fgets( $handle ) ) !== false ) {
if ( $line === "\n" || $line[0] === '#' ) {
continue;
}
[ $data ] = explode( '#', $line );
$data = array_map( 'trim', explode( ';', $data ) );
[ $codePoints, $combiningClass ] = $data;
if ( $combiningClass !== '9' ) {
continue;
}
$codePoints = self::parseCodePoints( $codePoints );
$diff = $codePoints[1] - $codePoints[0] + 1;
for ( $i = 0; $i < $diff; ++ $i ) {
$virama[ $codePoints[0] + $i ] = (int) $combiningClass;
}
}
fclose( $handle );
file_put_contents( $output . DS . 'virama.php', "<?php\n\nreturn " . var_export( $virama, true ) . ";\n" );
}
}
@@ -0,0 +1,17 @@
<?php
declare( strict_types=1 );
use VendorPrefix\Rowbot\Idna\Bin\IdnaDataBuilder;
use VendorPrefix\Rowbot\Idna\Bin\RegexBuilder;
use VendorPrefix\Rowbot\Idna\Bin\ViramaDataBuilder;
const DS = DIRECTORY_SEPARATOR;
const ROOT_DIR = __DIR__ . DS . '..';
const OUTPUT_DIR = ROOT_DIR . DS . 'resources';
require ROOT_DIR . DS . 'vendor' . DS . 'autoload.php';
ViramaDataBuilder::buildHashMap( OUTPUT_DIR );
RegexBuilder::buildRegexClass( OUTPUT_DIR );
IdnaDataBuilder::buildHashMaps( OUTPUT_DIR );
@@ -0,0 +1,49 @@
{
"name": "rowbot/idna",
"description": "An implementation of UTS#46 Unicode IDNA Compatibility Processing.",
"keywords": [
"idna",
"unicode",
"tr46",
"international domain names",
"uts46",
"iri",
"idn"
],
"type": "library",
"license": "MIT",
"authors": [
{
"name": "Trevor Rowbotham"
}
],
"config": {
"sort-packages": true
},
"autoload": {
"psr-4": {
"VendorPrefix\\Rowbot\\Idna\\": "src/",
"VendorPrefix\\Rowbot\\Idna\\Resource\\": "resources/"
}
},
"autoload-dev": {
"psr-4": {
"VendorPrefix\\Rowbot\\Idna\\Bin\\": "bin/",
"VendorPrefix\\Rowbot\\Idna\\Test\\": "tests/"
}
},
"require": {
"php": ">=7.1",
"rowbot/punycode": "^1.0",
"symfony/polyfill-intl-normalizer": "^1.18"
},
"require-dev": {
"guzzlehttp/guzzle": "^6.5 || ^7.0",
"phpstan/phpstan": "^1.2",
"phpstan/phpstan-deprecation-rules": "^1.0",
"phpstan/phpstan-strict-rules": "^1.0",
"phpunit/phpunit": "^7.0 || ^8.0 || ^9.0",
"squizlabs/php_codesniffer": "^3.5.1",
"symfony/cache": "^4.3 || ^5.0"
}
}
@@ -0,0 +1,16 @@
includes:
- vendor/phpstan/phpstan-deprecation-rules/rules.neon
- vendor/phpstan/phpstan-strict-rules/rules.neon
parameters:
level: max
paths:
- src
- bin
ignoreErrors:
# This error can safely be ignored as we do these checks when building the data files.
-
message: "#Offset 'mapping' does not exist on array{status: string, mapping\\?: string}\\.#"
path: src/Idna.php
count: 2
@@ -0,0 +1,23 @@
<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/5.7/phpunit.xsd"
bootstrap="vendor/autoload.php"
backupGlobals="false"
beStrictAboutCoversAnnotation="true"
beStrictAboutOutputDuringTests="true"
beStrictAboutTestsThatDoNotTestAnything="true"
beStrictAboutTodoAnnotatedTests="true"
verbose="true">
<testsuite name="default">
<directory suffix="Test.php">tests</directory>
</testsuite>
<filter>
<whitelist processUncoveredFilesFromWhitelist="true">
<directory suffix=".php">src</directory>
<exclude>
<directory>src/Resources</directory>
</exclude>
</whitelist>
</filter>
</phpunit>
@@ -0,0 +1,359 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Rowbot\Idna\Resource;
final class DisallowedRanges {
public static function inRange( int $codePoint ): bool {
if ( $codePoint >= 128 && $codePoint <= 159 ) {
return true;
}
if ( $codePoint >= 3676 && $codePoint <= 3712 ) {
return true;
}
if ( $codePoint >= 3808 && $codePoint <= 3839 ) {
return true;
}
if ( $codePoint >= 4059 && $codePoint <= 4095 ) {
return true;
}
if ( $codePoint >= 4256 && $codePoint <= 4293 ) {
return true;
}
if ( $codePoint >= 6863 && $codePoint <= 6911 ) {
return true;
}
if ( $codePoint >= 11870 && $codePoint <= 11903 ) {
return true;
}
if ( $codePoint >= 55296 && $codePoint <= 57343 ) {
return true;
}
if ( $codePoint >= 57344 && $codePoint <= 63743 ) {
return true;
}
if ( $codePoint >= 64218 && $codePoint <= 64255 ) {
return true;
}
if ( $codePoint >= 64976 && $codePoint <= 65007 ) {
return true;
}
if ( $codePoint >= 65630 && $codePoint <= 65663 ) {
return true;
}
if ( $codePoint >= 65953 && $codePoint <= 65999 ) {
return true;
}
if ( $codePoint >= 66046 && $codePoint <= 66175 ) {
return true;
}
if ( $codePoint >= 66518 && $codePoint <= 66559 ) {
return true;
}
if ( $codePoint >= 67005 && $codePoint <= 67071 ) {
return true;
}
if ( $codePoint >= 67515 && $codePoint <= 67583 ) {
return true;
}
if ( $codePoint >= 67760 && $codePoint <= 67807 ) {
return true;
}
if ( $codePoint >= 67904 && $codePoint <= 67967 ) {
return true;
}
if ( $codePoint >= 68256 && $codePoint <= 68287 ) {
return true;
}
if ( $codePoint >= 68528 && $codePoint <= 68607 ) {
return true;
}
if ( $codePoint >= 68681 && $codePoint <= 68735 ) {
return true;
}
if ( $codePoint >= 68922 && $codePoint <= 69215 ) {
return true;
}
if ( $codePoint >= 69298 && $codePoint <= 69375 ) {
return true;
}
if ( $codePoint >= 69514 && $codePoint <= 69551 ) {
return true;
}
if ( $codePoint >= 70207 && $codePoint <= 70271 ) {
return true;
}
if ( $codePoint >= 70517 && $codePoint <= 70655 ) {
return true;
}
if ( $codePoint >= 70874 && $codePoint <= 71039 ) {
return true;
}
if ( $codePoint >= 71134 && $codePoint <= 71167 ) {
return true;
}
if ( $codePoint >= 71370 && $codePoint <= 71423 ) {
return true;
}
if ( $codePoint >= 71495 && $codePoint <= 71679 ) {
return true;
}
if ( $codePoint >= 71740 && $codePoint <= 71839 ) {
return true;
}
if ( $codePoint >= 72026 && $codePoint <= 72095 ) {
return true;
}
if ( $codePoint >= 72441 && $codePoint <= 72703 ) {
return true;
}
if ( $codePoint >= 72887 && $codePoint <= 72959 ) {
return true;
}
if ( $codePoint >= 73130 && $codePoint <= 73439 ) {
return true;
}
if ( $codePoint >= 73465 && $codePoint <= 73647 ) {
return true;
}
if ( $codePoint >= 74650 && $codePoint <= 74751 ) {
return true;
}
if ( $codePoint >= 75076 && $codePoint <= 77711 ) {
return true;
}
if ( $codePoint >= 78905 && $codePoint <= 82943 ) {
return true;
}
if ( $codePoint >= 83527 && $codePoint <= 92159 ) {
return true;
}
if ( $codePoint >= 93072 && $codePoint <= 93759 ) {
return true;
}
if ( $codePoint >= 93851 && $codePoint <= 93951 ) {
return true;
}
if ( $codePoint >= 94112 && $codePoint <= 94175 ) {
return true;
}
if ( $codePoint >= 101590 && $codePoint <= 101631 ) {
return true;
}
if ( $codePoint >= 101641 && $codePoint <= 110575 ) {
return true;
}
if ( $codePoint >= 110883 && $codePoint <= 110927 ) {
return true;
}
if ( $codePoint >= 111356 && $codePoint <= 113663 ) {
return true;
}
if ( $codePoint >= 113828 && $codePoint <= 118527 ) {
return true;
}
if ( $codePoint >= 118724 && $codePoint <= 118783 ) {
return true;
}
if ( $codePoint >= 119366 && $codePoint <= 119519 ) {
return true;
}
if ( $codePoint >= 119673 && $codePoint <= 119807 ) {
return true;
}
if ( $codePoint >= 121520 && $codePoint <= 122623 ) {
return true;
}
if ( $codePoint >= 122655 && $codePoint <= 122879 ) {
return true;
}
if ( $codePoint >= 122923 && $codePoint <= 123135 ) {
return true;
}
if ( $codePoint >= 123216 && $codePoint <= 123535 ) {
return true;
}
if ( $codePoint >= 123648 && $codePoint <= 124895 ) {
return true;
}
if ( $codePoint >= 125143 && $codePoint <= 125183 ) {
return true;
}
if ( $codePoint >= 125280 && $codePoint <= 126064 ) {
return true;
}
if ( $codePoint >= 126133 && $codePoint <= 126208 ) {
return true;
}
if ( $codePoint >= 126270 && $codePoint <= 126463 ) {
return true;
}
if ( $codePoint >= 126652 && $codePoint <= 126703 ) {
return true;
}
if ( $codePoint >= 126706 && $codePoint <= 126975 ) {
return true;
}
if ( $codePoint >= 127406 && $codePoint <= 127461 ) {
return true;
}
if ( $codePoint >= 127590 && $codePoint <= 127743 ) {
return true;
}
if ( $codePoint >= 129202 && $codePoint <= 129279 ) {
return true;
}
if ( $codePoint >= 129995 && $codePoint <= 130031 ) {
return true;
}
if ( $codePoint >= 130042 && $codePoint <= 131069 ) {
return true;
}
if ( $codePoint >= 173792 && $codePoint <= 173823 ) {
return true;
}
if ( $codePoint >= 191457 && $codePoint <= 194559 ) {
return true;
}
if ( $codePoint >= 195102 && $codePoint <= 196605 ) {
return true;
}
if ( $codePoint >= 201547 && $codePoint <= 262141 ) {
return true;
}
if ( $codePoint >= 262144 && $codePoint <= 327677 ) {
return true;
}
if ( $codePoint >= 327680 && $codePoint <= 393213 ) {
return true;
}
if ( $codePoint >= 393216 && $codePoint <= 458749 ) {
return true;
}
if ( $codePoint >= 458752 && $codePoint <= 524285 ) {
return true;
}
if ( $codePoint >= 524288 && $codePoint <= 589821 ) {
return true;
}
if ( $codePoint >= 589824 && $codePoint <= 655357 ) {
return true;
}
if ( $codePoint >= 655360 && $codePoint <= 720893 ) {
return true;
}
if ( $codePoint >= 720896 && $codePoint <= 786429 ) {
return true;
}
if ( $codePoint >= 786432 && $codePoint <= 851965 ) {
return true;
}
if ( $codePoint >= 851968 && $codePoint <= 917501 ) {
return true;
}
if ( $codePoint >= 917536 && $codePoint <= 917631 ) {
return true;
}
if ( $codePoint >= 917632 && $codePoint <= 917759 ) {
return true;
}
if ( $codePoint >= 918000 && $codePoint <= 983037 ) {
return true;
}
if ( $codePoint >= 983040 && $codePoint <= 1048573 ) {
return true;
}
if ( $codePoint >= 1048576 && $codePoint <= 1114109 ) {
return true;
}
return false;
}
}
@@ -0,0 +1,8 @@
<?php
return array(
223 => 'ss',
962 => 'σ',
8204 => '',
8205 => '',
);
@@ -0,0 +1,308 @@
<?php
return array(
160 => ' ',
168 => ' ̈',
175 => ' ̄',
180 => ' ́',
184 => ' ̧',
728 => ' ̆',
729 => ' ̇',
730 => ' ̊',
731 => ' ̨',
732 => ' ̃',
733 => ' ̋',
890 => ' ι',
894 => ';',
900 => ' ́',
901 => ' ̈́',
8125 => ' ̓',
8127 => ' ̓',
8128 => ' ͂',
8129 => ' ̈͂',
8141 => ' ̓̀',
8142 => ' ̓́',
8143 => ' ̓͂',
8157 => ' ̔̀',
8158 => ' ̔́',
8159 => ' ̔͂',
8173 => ' ̈̀',
8174 => ' ̈́',
8175 => '`',
8189 => ' ́',
8190 => ' ̔',
8192 => ' ',
8193 => ' ',
8194 => ' ',
8195 => ' ',
8196 => ' ',
8197 => ' ',
8198 => ' ',
8199 => ' ',
8200 => ' ',
8201 => ' ',
8202 => ' ',
8215 => ' ̳',
8239 => ' ',
8252 => '!!',
8254 => ' ̅',
8263 => '??',
8264 => '?!',
8265 => '!?',
8287 => ' ',
8314 => '+',
8316 => '=',
8317 => '(',
8318 => ')',
8330 => '+',
8332 => '=',
8333 => '(',
8334 => ')',
8448 => 'a/c',
8449 => 'a/s',
8453 => 'c/o',
8454 => 'c/u',
9332 => '(1)',
9333 => '(2)',
9334 => '(3)',
9335 => '(4)',
9336 => '(5)',
9337 => '(6)',
9338 => '(7)',
9339 => '(8)',
9340 => '(9)',
9341 => '(10)',
9342 => '(11)',
9343 => '(12)',
9344 => '(13)',
9345 => '(14)',
9346 => '(15)',
9347 => '(16)',
9348 => '(17)',
9349 => '(18)',
9350 => '(19)',
9351 => '(20)',
9372 => '(a)',
9373 => '(b)',
9374 => '(c)',
9375 => '(d)',
9376 => '(e)',
9377 => '(f)',
9378 => '(g)',
9379 => '(h)',
9380 => '(i)',
9381 => '(j)',
9382 => '(k)',
9383 => '(l)',
9384 => '(m)',
9385 => '(n)',
9386 => '(o)',
9387 => '(p)',
9388 => '(q)',
9389 => '(r)',
9390 => '(s)',
9391 => '(t)',
9392 => '(u)',
9393 => '(v)',
9394 => '(w)',
9395 => '(x)',
9396 => '(y)',
9397 => '(z)',
10868 => '::=',
10869 => '==',
10870 => '===',
12288 => ' ',
12443 => ' ゙',
12444 => ' ゚',
12800 => '(ᄀ)',
12801 => '(ᄂ)',
12802 => '(ᄃ)',
12803 => '(ᄅ)',
12804 => '(ᄆ)',
12805 => '(ᄇ)',
12806 => '(ᄉ)',
12807 => '(ᄋ)',
12808 => '(ᄌ)',
12809 => '(ᄎ)',
12810 => '(ᄏ)',
12811 => '(ᄐ)',
12812 => '(ᄑ)',
12813 => '(ᄒ)',
12814 => '(가)',
12815 => '(나)',
12816 => '(다)',
12817 => '(라)',
12818 => '(마)',
12819 => '(바)',
12820 => '(사)',
12821 => '(아)',
12822 => '(자)',
12823 => '(차)',
12824 => '(카)',
12825 => '(타)',
12826 => '(파)',
12827 => '(하)',
12828 => '(주)',
12829 => '(오전)',
12830 => '(오후)',
12832 => '(一)',
12833 => '(二)',
12834 => '(三)',
12835 => '(四)',
12836 => '(五)',
12837 => '(六)',
12838 => '(七)',
12839 => '(八)',
12840 => '(九)',
12841 => '(十)',
12842 => '(月)',
12843 => '(火)',
12844 => '(水)',
12845 => '(木)',
12846 => '(金)',
12847 => '(土)',
12848 => '(日)',
12849 => '(株)',
12850 => '(有)',
12851 => '(社)',
12852 => '(名)',
12853 => '(特)',
12854 => '(財)',
12855 => '(祝)',
12856 => '(労)',
12857 => '(代)',
12858 => '(呼)',
12859 => '(学)',
12860 => '(監)',
12861 => '(企)',
12862 => '(資)',
12863 => '(協)',
12864 => '(祭)',
12865 => '(休)',
12866 => '(自)',
12867 => '(至)',
64297 => '+',
64606 => ' ٌّ',
64607 => ' ٍّ',
64608 => ' َّ',
64609 => ' ُّ',
64610 => ' ِّ',
64611 => ' ّٰ',
65018 => 'صلى الله عليه وسلم',
65019 => 'جل جلاله',
65040 => ',',
65043 => ':',
65044 => ';',
65045 => '!',
65046 => '?',
65075 => '_',
65076 => '_',
65077 => '(',
65078 => ')',
65079 => '{',
65080 => '}',
65095 => '[',
65096 => ']',
65097 => ' ̅',
65098 => ' ̅',
65099 => ' ̅',
65100 => ' ̅',
65101 => '_',
65102 => '_',
65103 => '_',
65104 => ',',
65108 => ';',
65109 => ':',
65110 => '?',
65111 => '!',
65113 => '(',
65114 => ')',
65115 => '{',
65116 => '}',
65119 => '#',
65120 => '&',
65121 => '*',
65122 => '+',
65124 => '<',
65125 => '>',
65126 => '=',
65128 => '\\',
65129 => '$',
65130 => '%',
65131 => '@',
65136 => ' ً',
65138 => ' ٌ',
65140 => ' ٍ',
65142 => ' َ',
65144 => ' ُ',
65146 => ' ِ',
65148 => ' ّ',
65150 => ' ْ',
65281 => '!',
65282 => '"',
65283 => '#',
65284 => '$',
65285 => '%',
65286 => '&',
65287 => '\'',
65288 => '(',
65289 => ')',
65290 => '*',
65291 => '+',
65292 => ',',
65295 => '/',
65306 => ':',
65307 => ';',
65308 => '<',
65309 => '=',
65310 => '>',
65311 => '?',
65312 => '@',
65339 => '[',
65340 => '\\',
65341 => ']',
65342 => '^',
65343 => '_',
65344 => '`',
65371 => '{',
65372 => '|',
65373 => '}',
65374 => '~',
65507 => ' ̄',
127233 => '0,',
127234 => '1,',
127235 => '2,',
127236 => '3,',
127237 => '4,',
127238 => '5,',
127239 => '6,',
127240 => '7,',
127241 => '8,',
127242 => '9,',
127248 => '(a)',
127249 => '(b)',
127250 => '(c)',
127251 => '(d)',
127252 => '(e)',
127253 => '(f)',
127254 => '(g)',
127255 => '(h)',
127256 => '(i)',
127257 => '(j)',
127258 => '(k)',
127259 => '(l)',
127260 => '(m)',
127261 => '(n)',
127262 => '(o)',
127263 => '(p)',
127264 => '(q)',
127265 => '(r)',
127266 => '(s)',
127267 => '(t)',
127268 => '(u)',
127269 => '(v)',
127270 => '(w)',
127271 => '(x)',
127272 => '(y)',
127273 => '(z)',
);
@@ -0,0 +1,71 @@
<?php
return array(
0 => true,
1 => true,
2 => true,
3 => true,
4 => true,
5 => true,
6 => true,
7 => true,
8 => true,
9 => true,
10 => true,
11 => true,
12 => true,
13 => true,
14 => true,
15 => true,
16 => true,
17 => true,
18 => true,
19 => true,
20 => true,
21 => true,
22 => true,
23 => true,
24 => true,
25 => true,
26 => true,
27 => true,
28 => true,
29 => true,
30 => true,
31 => true,
32 => true,
33 => true,
34 => true,
35 => true,
36 => true,
37 => true,
38 => true,
39 => true,
40 => true,
41 => true,
42 => true,
43 => true,
44 => true,
47 => true,
58 => true,
59 => true,
60 => true,
61 => true,
62 => true,
63 => true,
64 => true,
91 => true,
92 => true,
93 => true,
94 => true,
95 => true,
96 => true,
123 => true,
124 => true,
125 => true,
126 => true,
127 => true,
8800 => true,
8814 => true,
8815 => true,
);
@@ -0,0 +1,274 @@
<?php
return array(
173 => true,
847 => true,
6155 => true,
6156 => true,
6157 => true,
6159 => true,
8203 => true,
8288 => true,
8292 => true,
65024 => true,
65025 => true,
65026 => true,
65027 => true,
65028 => true,
65029 => true,
65030 => true,
65031 => true,
65032 => true,
65033 => true,
65034 => true,
65035 => true,
65036 => true,
65037 => true,
65038 => true,
65039 => true,
65279 => true,
113824 => true,
113825 => true,
113826 => true,
113827 => true,
917760 => true,
917761 => true,
917762 => true,
917763 => true,
917764 => true,
917765 => true,
917766 => true,
917767 => true,
917768 => true,
917769 => true,
917770 => true,
917771 => true,
917772 => true,
917773 => true,
917774 => true,
917775 => true,
917776 => true,
917777 => true,
917778 => true,
917779 => true,
917780 => true,
917781 => true,
917782 => true,
917783 => true,
917784 => true,
917785 => true,
917786 => true,
917787 => true,
917788 => true,
917789 => true,
917790 => true,
917791 => true,
917792 => true,
917793 => true,
917794 => true,
917795 => true,
917796 => true,
917797 => true,
917798 => true,
917799 => true,
917800 => true,
917801 => true,
917802 => true,
917803 => true,
917804 => true,
917805 => true,
917806 => true,
917807 => true,
917808 => true,
917809 => true,
917810 => true,
917811 => true,
917812 => true,
917813 => true,
917814 => true,
917815 => true,
917816 => true,
917817 => true,
917818 => true,
917819 => true,
917820 => true,
917821 => true,
917822 => true,
917823 => true,
917824 => true,
917825 => true,
917826 => true,
917827 => true,
917828 => true,
917829 => true,
917830 => true,
917831 => true,
917832 => true,
917833 => true,
917834 => true,
917835 => true,
917836 => true,
917837 => true,
917838 => true,
917839 => true,
917840 => true,
917841 => true,
917842 => true,
917843 => true,
917844 => true,
917845 => true,
917846 => true,
917847 => true,
917848 => true,
917849 => true,
917850 => true,
917851 => true,
917852 => true,
917853 => true,
917854 => true,
917855 => true,
917856 => true,
917857 => true,
917858 => true,
917859 => true,
917860 => true,
917861 => true,
917862 => true,
917863 => true,
917864 => true,
917865 => true,
917866 => true,
917867 => true,
917868 => true,
917869 => true,
917870 => true,
917871 => true,
917872 => true,
917873 => true,
917874 => true,
917875 => true,
917876 => true,
917877 => true,
917878 => true,
917879 => true,
917880 => true,
917881 => true,
917882 => true,
917883 => true,
917884 => true,
917885 => true,
917886 => true,
917887 => true,
917888 => true,
917889 => true,
917890 => true,
917891 => true,
917892 => true,
917893 => true,
917894 => true,
917895 => true,
917896 => true,
917897 => true,
917898 => true,
917899 => true,
917900 => true,
917901 => true,
917902 => true,
917903 => true,
917904 => true,
917905 => true,
917906 => true,
917907 => true,
917908 => true,
917909 => true,
917910 => true,
917911 => true,
917912 => true,
917913 => true,
917914 => true,
917915 => true,
917916 => true,
917917 => true,
917918 => true,
917919 => true,
917920 => true,
917921 => true,
917922 => true,
917923 => true,
917924 => true,
917925 => true,
917926 => true,
917927 => true,
917928 => true,
917929 => true,
917930 => true,
917931 => true,
917932 => true,
917933 => true,
917934 => true,
917935 => true,
917936 => true,
917937 => true,
917938 => true,
917939 => true,
917940 => true,
917941 => true,
917942 => true,
917943 => true,
917944 => true,
917945 => true,
917946 => true,
917947 => true,
917948 => true,
917949 => true,
917950 => true,
917951 => true,
917952 => true,
917953 => true,
917954 => true,
917955 => true,
917956 => true,
917957 => true,
917958 => true,
917959 => true,
917960 => true,
917961 => true,
917962 => true,
917963 => true,
917964 => true,
917965 => true,
917966 => true,
917967 => true,
917968 => true,
917969 => true,
917970 => true,
917971 => true,
917972 => true,
917973 => true,
917974 => true,
917975 => true,
917976 => true,
917977 => true,
917978 => true,
917979 => true,
917980 => true,
917981 => true,
917982 => true,
917983 => true,
917984 => true,
917985 => true,
917986 => true,
917987 => true,
917988 => true,
917989 => true,
917990 => true,
917991 => true,
917992 => true,
917993 => true,
917994 => true,
917995 => true,
917996 => true,
917997 => true,
917998 => true,
917999 => true,
);
@@ -0,0 +1,67 @@
<?php
return array(
2381 => 9,
2509 => 9,
2637 => 9,
2765 => 9,
2893 => 9,
3021 => 9,
3149 => 9,
3277 => 9,
3387 => 9,
3388 => 9,
3405 => 9,
3530 => 9,
3642 => 9,
3770 => 9,
3972 => 9,
4153 => 9,
4154 => 9,
5908 => 9,
5909 => 9,
5940 => 9,
6098 => 9,
6752 => 9,
6980 => 9,
7082 => 9,
7083 => 9,
7154 => 9,
7155 => 9,
11647 => 9,
43014 => 9,
43052 => 9,
43204 => 9,
43347 => 9,
43456 => 9,
43766 => 9,
44013 => 9,
68159 => 9,
69702 => 9,
69744 => 9,
69759 => 9,
69817 => 9,
69939 => 9,
69940 => 9,
70080 => 9,
70197 => 9,
70378 => 9,
70477 => 9,
70722 => 9,
70850 => 9,
71103 => 9,
71231 => 9,
71350 => 9,
71467 => 9,
71737 => 9,
71997 => 9,
71998 => 9,
72160 => 9,
72244 => 9,
72263 => 9,
72345 => 9,
72767 => 9,
73028 => 9,
73029 => 9,
73111 => 9,
);
@@ -0,0 +1,136 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Rowbot\Idna;
use function chr;
use function ord;
use function strlen;
final class CodePoint {
/**
* Takes a Unicode code point and encodes it. The return behavior is undefined if the given
* code point is outside the range 0..10FFFF.
*
* @see https://encoding.spec.whatwg.org/#utf-8-encoder
*/
public static function encode( int $codePoint ): string {
if ( $codePoint >= 0x00 && $codePoint <= 0x7F ) {
return chr( $codePoint );
}
$count = 0;
$offset = 0;
if ( $codePoint >= 0x0080 && $codePoint <= 0x07FF ) {
$count = 1;
$offset = 0xC0;
} elseif ( $codePoint >= 0x0800 && $codePoint <= 0xFFFF ) {
$count = 2;
$offset = 0xE0;
} elseif ( $codePoint >= 0x10000 && $codePoint <= 0x10FFFF ) {
$count = 3;
$offset = 0xF0;
}
$bytes = chr( ( $codePoint >> ( 6 * $count ) ) + $offset );
while ( $count > 0 ) {
$temp = $codePoint >> ( 6 * ( $count - 1 ) );
$bytes .= chr( 0x80 | ( $temp & 0x3F ) );
-- $count;
}
return $bytes;
}
/**
* Takes a UTF-8 encoded string and converts it into a series of integer code points. Any
* invalid byte sequences will be replaced by a U+FFFD replacement code point.
*
* @see https://encoding.spec.whatwg.org/#utf-8-decoder
*
* @return list<int>
*/
public static function utf8Decode( string $input ): array {
$bytesSeen = 0;
$bytesNeeded = 0;
$lowerBoundary = 0x80;
$upperBoundary = 0xBF;
$codePoint = 0;
$codePoints = [];
$length = strlen( $input );
for ( $i = 0; $i < $length; ++ $i ) {
$byte = ord( $input[ $i ] );
if ( $bytesNeeded === 0 ) {
if ( $byte >= 0x00 && $byte <= 0x7F ) {
$codePoints[] = $byte;
continue;
}
if ( $byte >= 0xC2 && $byte <= 0xDF ) {
$bytesNeeded = 1;
$codePoint = $byte & 0x1F;
} elseif ( $byte >= 0xE0 && $byte <= 0xEF ) {
if ( $byte === 0xE0 ) {
$lowerBoundary = 0xA0;
} elseif ( $byte === 0xED ) {
$upperBoundary = 0x9F;
}
$bytesNeeded = 2;
$codePoint = $byte & 0xF;
} elseif ( $byte >= 0xF0 && $byte <= 0xF4 ) {
if ( $byte === 0xF0 ) {
$lowerBoundary = 0x90;
} elseif ( $byte === 0xF4 ) {
$upperBoundary = 0x8F;
}
$bytesNeeded = 3;
$codePoint = $byte & 0x7;
} else {
$codePoints[] = 0xFFFD;
}
continue;
}
if ( $byte < $lowerBoundary || $byte > $upperBoundary ) {
$codePoint = 0;
$bytesNeeded = 0;
$bytesSeen = 0;
$lowerBoundary = 0x80;
$upperBoundary = 0xBF;
-- $i;
$codePoints[] = 0xFFFD;
continue;
}
$lowerBoundary = 0x80;
$upperBoundary = 0xBF;
$codePoint = ( $codePoint << 6 ) | ( $byte & 0x3F );
if ( ++ $bytesSeen !== $bytesNeeded ) {
continue;
}
$codePoints[] = $codePoint;
$codePoint = 0;
$bytesNeeded = 0;
$bytesSeen = 0;
}
// String unexpectedly ended, so append a U+FFFD code point.
if ( $bytesNeeded !== 0 ) {
$codePoints[] = 0xFFFD;
}
return $codePoints;
}
}
@@ -0,0 +1,103 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Rowbot\Idna;
use VendorPrefix\Rowbot\Idna\Resource\DisallowedRanges;
use const DIRECTORY_SEPARATOR as DS;
final class CodePointStatus {
private const RESOURCE_DIR = __DIR__ . DS . '..' . DS . 'resources' . DS;
/**
* @var array<int, string>
*/
private static $mapped;
/**
* @var array<int, bool>
*/
private static $ignored;
/**
* @var array<int, string>
*/
private static $deviation;
/**
* @var array<int, bool>
*/
private static $disallowed;
/**
* @var array<int, string>
*/
private static $disallowed_STD3_mapped;
/**
* @var array<int, bool>
*/
private static $disallowed_STD3_valid;
/**
* @var bool
*/
private static $dataLoaded = false;
/**
* @codeCoverageIgnore
*/
private function __construct() {
}
/**
* @return array{status: string, mapping?: string}
*/
public static function lookup( int $codePoint, bool $useSTD3ASCIIRules ): array {
if ( ! self::$dataLoaded ) {
self::$dataLoaded = true;
self::$mapped = require self::RESOURCE_DIR . 'mapped.php';
self::$ignored = require self::RESOURCE_DIR . 'ignored.php';
self::$deviation = require self::RESOURCE_DIR . 'deviation.php';
self::$disallowed = require self::RESOURCE_DIR . 'disallowed.php';
self::$disallowed_STD3_mapped = require self::RESOURCE_DIR . 'disallowed_STD3_mapped.php';
self::$disallowed_STD3_valid = require self::RESOURCE_DIR . 'disallowed_STD3_valid.php';
}
if ( isset( self::$mapped[ $codePoint ] ) ) {
return [ 'status' => 'mapped', 'mapping' => self::$mapped[ $codePoint ] ];
}
if ( isset( self::$ignored[ $codePoint ] ) ) {
return [ 'status' => 'ignored' ];
}
if ( isset( self::$deviation[ $codePoint ] ) ) {
return [ 'status' => 'deviation', 'mapping' => self::$deviation[ $codePoint ] ];
}
if ( isset( self::$disallowed[ $codePoint ] ) || DisallowedRanges::inRange( $codePoint ) ) {
return [ 'status' => 'disallowed' ];
}
$isDisallowedMapped = isset( self::$disallowed_STD3_mapped[ $codePoint ] );
if ( $isDisallowedMapped || isset( self::$disallowed_STD3_valid[ $codePoint ] ) ) {
$status = 'disallowed';
if ( ! $useSTD3ASCIIRules ) {
$status = $isDisallowedMapped ? 'mapped' : 'valid';
}
if ( $isDisallowedMapped ) {
return [ 'status' => $status, 'mapping' => self::$disallowed_STD3_mapped[ $codePoint ] ];
}
return [ 'status' => $status ];
}
return [ 'status' => 'valid' ];
}
}
@@ -0,0 +1,72 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Rowbot\Idna;
class DomainInfo {
/**
* @var bool
*/
protected $bidiDomain;
/**
* @var int
*/
protected $errors;
/**
* @var bool
*/
protected $validBidiDomain;
/**
* @var bool
*/
protected $transitionalDifferent;
public function __construct() {
$this->bidiDomain = false;
$this->errors = 0;
$this->transitionalDifferent = false;
$this->validBidiDomain = true;
}
public function addError( int $errors ): void {
$this->errors |= $errors;
}
public function getErrors(): int {
return $this->errors;
}
/**
* A Bidi domain name is a domain name containing at least one character with Bidi_Class R, AL, or AN.
*
* @see https://www.unicode.org/reports/tr46/#Notation
* @see https://www.unicode.org/reports/tr9/#Bidirectional_Character_Types
*/
public function isBidiDomain(): bool {
return $this->bidiDomain;
}
public function isTransitionalDifferent(): bool {
return $this->transitionalDifferent;
}
public function isValidBidiDomain(): bool {
return $this->validBidiDomain;
}
public function setBidiDomain(): void {
$this->bidiDomain = true;
}
public function setInvalidBidiDomain(): void {
$this->validBidiDomain = false;
}
public function setTransitionalDifferent(): void {
$this->transitionalDifferent = true;
}
}
@@ -0,0 +1,261 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Rowbot\Idna;
use Normalizer;
use VendorPrefix\Rowbot\Punycode\Exception\PunycodeException;
use VendorPrefix\Rowbot\Punycode\Punycode;
use function array_merge;
use function count;
use function explode;
use function implode;
use function preg_match;
use function strlen;
use function strncmp;
use function substr;
/**
* @see https://www.unicode.org/reports/tr46/
*/
final class Idna {
public const UNICODE_VERSION = '14.0.0';
private const DEFAULT_UNICODE_OPTIONS = [
'CheckHyphens' => true,
'CheckBidi' => true,
'CheckJoiners' => true,
'UseSTD3ASCIIRules' => true,
'Transitional_Processing' => false,
];
private const DEFAULT_ASCII_OPTIONS = self::DEFAULT_UNICODE_OPTIONS + [
'VerifyDnsLength' => true,
];
public const ERROR_EMPTY_LABEL = 1;
public const ERROR_LABEL_TOO_LONG = 2;
public const ERROR_DOMAIN_NAME_TOO_LONG = 4;
public const ERROR_LEADING_HYPHEN = 8;
public const ERROR_TRAILING_HYPHEN = 0x10;
public const ERROR_HYPHEN_3_4 = 0x20;
public const ERROR_LEADING_COMBINING_MARK = 0x40;
public const ERROR_DISALLOWED = 0x80;
public const ERROR_PUNYCODE = 0x100;
public const ERROR_LABEL_HAS_DOT = 0x200;
public const ERROR_INVALID_ACE_LABEL = 0x400;
public const ERROR_BIDI = 0x800;
public const ERROR_CONTEXTJ = 0x1000;
public const ERROR_CONTEXTO_PUNCTUATION = 0x2000;
public const ERROR_CONTEXTO_DIGITS = 0x4000;
private const MAX_DOMAIN_SIZE = 253;
private const MAX_LABEL_SIZE = 63;
/**
* @codeCoverageIgnore
*/
private function __construct() {
}
/**
* @see https://www.unicode.org/reports/tr46/#ProcessingStepMap
*
* @param array<string, bool> $options
*/
private static function mapCodePoints( string $domain, array $options, DomainInfo $info ): string {
$str = '';
$useSTD3ASCIIRules = $options['UseSTD3ASCIIRules'];
$transitional = $options['Transitional_Processing'];
$errors = 0;
$transitionalDifferent = false;
foreach ( CodePoint::utf8Decode( $domain ) as $codePoint ) {
$data = CodePointStatus::lookup( $codePoint, $useSTD3ASCIIRules );
switch ( $data['status'] ) {
case 'disallowed':
$errors |= Idna::ERROR_DISALLOWED;
// no break.
case 'valid':
$str .= CodePoint::encode( $codePoint );
break;
case 'ignored':
// Do nothing.
break;
case 'mapped':
$str .= $data['mapping'];
break;
case 'deviation':
$transitionalDifferent = true;
$str .= ( $transitional ? $data['mapping'] : CodePoint::encode( $codePoint ) );
break;
}
}
$info->addError( $errors );
if ( $transitionalDifferent ) {
$info->setTransitionalDifferent();
}
return $str;
}
/**
* @see https://www.unicode.org/reports/tr46/#Processing
*
* @param array<string, bool> $options
*
* @return list<string>
*/
private static function process( string $domain, array $options, DomainInfo $info ): array {
// If VerifyDnsLength is not set, we are doing ToUnicode otherwise we are doing ToASCII and
// we need to respect the VerifyDnsLength option.
$checkForEmptyLabels = ! isset( $options['VerifyDnsLength'] ) || $options['VerifyDnsLength'];
if ( $checkForEmptyLabels && $domain === '' ) {
$info->addError( self::ERROR_EMPTY_LABEL );
return [ '' ];
}
// Step 1. Map each code point in the domain name string
$domain = self::mapCodePoints( $domain, $options, $info );
// Step 2. Normalize the domain name string to Unicode Normalization Form C.
if ( ! Normalizer::isNormalized( $domain, Normalizer::FORM_C ) ) {
$originalDomain = $domain;
$domain = Normalizer::normalize( $domain, Normalizer::FORM_C );
// This shouldn't be possible since the input string is run through the UTF-8 decoder
// when mapping the code points above, but lets account for it anyway.
if ( $domain === false ) {
$info->addError( self::ERROR_INVALID_ACE_LABEL );
$domain = $originalDomain;
}
unset( $originalDomain );
}
// Step 3. Break the string into labels at U+002E (.) FULL STOP.
$labels = explode( '.', $domain );
$lastLabelIndex = count( $labels ) - 1;
$validator = new LabelValidator( $info );
// Step 4. Convert and validate each label in the domain name string.
foreach ( $labels as $i => $label ) {
$validationOptions = $options;
if ( strncmp( $label, 'xn--', 4 ) === 0 ) {
try {
$label = Punycode::decode( substr( $label, 4 ) );
} catch ( PunycodeException $e ) {
$info->addError( self::ERROR_PUNYCODE );
continue;
}
$validationOptions['Transitional_Processing'] = false;
$labels[ $i ] = $label;
}
$validator->validate( $label, $validationOptions, $i > 0 && $i === $lastLabelIndex );
}
if ( $info->isBidiDomain() && ! $info->isValidBidiDomain() ) {
$info->addError( self::ERROR_BIDI );
}
// Any input domain name string that does not record an error has been successfully
// processed according to this specification. Conversely, if an input domain_name string
// causes an error, then the processing of the input domain_name string fails. Determining
// what to do with error input is up to the caller, and not in the scope of this document.
return $labels;
}
/**
* @see https://www.unicode.org/reports/tr46/#ToASCII
*
* @param array<string, bool> $options
*/
public static function toAscii( string $domain, array $options = [] ): IdnaResult {
$options = array_merge( self::DEFAULT_ASCII_OPTIONS, $options );
$info = new DomainInfo();
$labels = self::process( $domain, $options, $info );
foreach ( $labels as $i => $label ) {
// Only convert labels to punycode that contain non-ASCII code points
if ( preg_match( '/[^\x00-\x7F]/', $label ) === 1 ) {
try {
$label = 'xn--' . Punycode::encode( $label );
} catch ( PunycodeException $e ) {
$info->addError( self::ERROR_PUNYCODE );
}
$labels[ $i ] = $label;
}
}
if ( $options['VerifyDnsLength'] ) {
self::validateDomainAndLabelLength( $labels, $info );
}
return new IdnaResult( implode( '.', $labels ), $info );
}
/**
* @see https://www.unicode.org/reports/tr46/#ToUnicode
*
* @param array<string, bool> $options
*/
public static function toUnicode( string $domain, array $options = [] ): IdnaResult {
// VerifyDnsLength is not a valid option for toUnicode, so remove it if it exists.
unset( $options['VerifyDnsLength'] );
$options = array_merge( self::DEFAULT_UNICODE_OPTIONS, $options );
$info = new DomainInfo();
$labels = self::process( $domain, $options, $info );
return new IdnaResult( implode( '.', $labels ), $info );
}
/**
* @param list<string> $labels
*/
private static function validateDomainAndLabelLength( array $labels, DomainInfo $info ): void {
$maxDomainSize = self::MAX_DOMAIN_SIZE;
$length = count( $labels );
$totalLength = $length - 1;
// If the last label is empty and it is not the first label, then it is the root label.
// Increase the max size by 1, making it 254, to account for the root label's "."
// delimiter. This also means we don't need to check the last label's length for being too
// long.
if ( $length > 1 && $labels[ $length - 1 ] === '' ) {
++ $maxDomainSize;
-- $length;
}
for ( $i = 0; $i < $length; ++ $i ) {
$bytes = strlen( $labels[ $i ] );
$totalLength += $bytes;
if ( $bytes > self::MAX_LABEL_SIZE ) {
$info->addError( self::ERROR_LABEL_TOO_LONG );
}
}
if ( $totalLength > $maxDomainSize ) {
$info->addError( self::ERROR_DOMAIN_NAME_TOO_LONG );
}
}
}
@@ -0,0 +1,48 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Rowbot\Idna;
class IdnaResult {
/**
* @var string
*/
protected $domain;
/**
* @var int
*/
protected $errors;
/**
* @var bool
*/
protected $transitionalDifferent;
public function __construct( string $domain, DomainInfo $info ) {
$this->domain = $domain;
$this->errors = $info->getErrors();
$this->transitionalDifferent = $info->isTransitionalDifferent();
}
public function getDomain(): string {
return $this->domain;
}
public function getErrors(): int {
return $this->errors;
}
public function hasError( int $error ): bool {
return ( $this->errors & $error ) !== 0;
}
public function hasErrors(): bool {
return $this->errors !== 0;
}
public function isTransitionalDifferent(): bool {
return $this->transitionalDifferent;
}
}
@@ -0,0 +1,232 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Rowbot\Idna;
use Normalizer;
use VendorPrefix\Rowbot\Idna\Resource\Regex;
use function preg_match;
use function strlen;
use function strpos;
use const DIRECTORY_SEPARATOR as DS;
use const PREG_OFFSET_CAPTURE;
class LabelValidator {
/**
* @var DomainInfo
*/
protected $info;
/**
* @var array<int, int>
*/
protected static $virama = [];
public function __construct( DomainInfo $info ) {
$this->info = $info;
if ( self::$virama === [] ) {
self::$virama = require __DIR__ . DS . '..' . DS . 'resources' . DS . 'virama.php';
}
}
/**
* @param list<int> $codePoints
*/
protected function isValidContextJ( string $label, array $codePoints ): bool {
$offset = 0;
foreach ( $codePoints as $i => $codePoint ) {
if ( $codePoint !== 0x200C && $codePoint !== 0x200D ) {
continue;
}
$prev = $i - 1;
if ( ! isset( $codePoints[ $prev ] ) ) {
return false;
}
// If Canonical_Combining_Class(Before(cp)) .eq. Virama Then True;
if ( isset( self::$virama[ $codePoints[ $prev ] ] ) ) {
continue;
}
// If RegExpMatch((Joining_Type:{L,D})(Joining_Type:T)*\u200C(Joining_Type:T)*(Joining_Type:{R,D})) Then
// True;
// Generated RegExp = ([Joining_Type:{L,D}][Joining_Type:T]*\u200C[Joining_Type:T]*)[Joining_Type:{R,D}]
if (
$codePoint === 0x200C
&& preg_match( Regex::ZWNJ, $label, $matches, PREG_OFFSET_CAPTURE, $offset ) === 1
) {
$offset += strlen( $matches[1][0] );
continue;
}
return false;
}
return true;
}
/**
* @see https://www.unicode.org/reports/tr46/#Validity_Criteria
*
* @param array<string, bool> $options
*/
public function validate( string $label, array $options, bool $canBeEmpty ): void {
if ( $label === '' ) {
if (
! $canBeEmpty
&& ( ! isset( $options['VerifyDnsLength'] ) || $options['VerifyDnsLength'] )
) {
$this->info->addError( Idna::ERROR_EMPTY_LABEL );
}
return;
}
$codePoints = CodePoint::utf8Decode( $label );
// Step 1. The label must be in Unicode Normalization Form C.
if ( ! Normalizer::isNormalized( $label, Normalizer::FORM_C ) ) {
$this->info->addError( Idna::ERROR_INVALID_ACE_LABEL );
}
if ( $options['CheckHyphens'] ) {
// Step 2. If CheckHyphens, the label must not contain a U+002D HYPHEN-MINUS character
// in both the thrid and fourth positions.
if ( isset( $codePoints[3] ) && $codePoints[2] === 0x2D && $codePoints[3] === 0x2D ) {
$this->info->addError( Idna::ERROR_HYPHEN_3_4 );
}
// Step 3. If CheckHyphens, the label must neither begin nor end with a U+002D
// HYPHEN-MINUS character.
if ( strncmp( $label, '-', 1 ) === 0 ) {
$this->info->addError( Idna::ERROR_LEADING_HYPHEN );
}
if ( substr_compare( $label, '-', - 1 ) === 0 ) {
$this->info->addError( Idna::ERROR_TRAILING_HYPHEN );
}
}
// Step 4. The label must not contain a U+002E (.) FULL STOP.
if ( strpos( $label, '.' ) !== false ) {
$this->info->addError( Idna::ERROR_LABEL_HAS_DOT );
}
// Step 5. The label must not begin with a combining mark, that is: General_Category=Mark.
if ( preg_match( Regex::COMBINING_MARK, $label, $matches ) === 1 ) {
$this->info->addError( Idna::ERROR_LEADING_COMBINING_MARK );
}
// Step 6. Each code point in the label must only have certain status values according to
// Section 5, IDNA Mapping Table:
$transitional = $options['Transitional_Processing'];
$useSTD3ASCIIRules = $options['UseSTD3ASCIIRules'];
foreach ( $codePoints as $codePoint ) {
$data = CodePointStatus::lookup( $codePoint, $useSTD3ASCIIRules );
$status = $data['status'];
if ( $status === 'valid' || ( ! $transitional && $status === 'deviation' ) ) {
continue;
}
$this->info->addError( Idna::ERROR_DISALLOWED );
break;
}
// Step 7. If CheckJoiners, the label must satisify the ContextJ rules from Appendix A, in
// The Unicode Code Points and Internationalized Domain Names for Applications (IDNA)
// [IDNA2008].
if ( $options['CheckJoiners'] && ! $this->isValidContextJ( $label, $codePoints ) ) {
$this->info->addError( Idna::ERROR_CONTEXTJ );
}
// Step 8. If CheckBidi, and if the domain name is a Bidi domain name, then the label must
// satisfy all six of the numbered conditions in [IDNA2008] RFC 5893, Section 2.
if (
$options['CheckBidi']
&& ( ! $this->info->isBidiDomain() || $this->info->isValidBidiDomain() )
) {
$this->validateBidi( $label );
}
}
/**
* @see https://tools.ietf.org/html/rfc5893#section-2
*/
protected function validateBidi( string $label ): void {
if ( preg_match( Regex::RTL_LABEL, $label ) === 1 ) {
$this->info->setBidiDomain();
// Step 1. The first character must be a character with Bidi property L, R, or AL.
// If it has the R or AL property, it is an RTL label
if ( preg_match( Regex::BIDI_STEP_1_RTL, $label ) !== 1 ) {
$this->info->setInvalidBidiDomain();
return;
}
// Step 2. In an RTL label, only characters with the Bidi properties R, AL, AN, EN, ES,
// CS, ET, ON, BN, or NSM are allowed.
if ( preg_match( Regex::BIDI_STEP_2, $label ) === 1 ) {
$this->info->setInvalidBidiDomain();
return;
}
// Step 3. In an RTL label, the end of the label must be a character with Bidi property
// R, AL, EN, or AN, followed by zero or more characters with Bidi property NSM.
if ( preg_match( Regex::BIDI_STEP_3, $label ) !== 1 ) {
$this->info->setInvalidBidiDomain();
return;
}
// Step 4. In an RTL label, if an EN is present, no AN may be present, and vice versa.
if (
preg_match( Regex::BIDI_STEP_4_AN, $label ) === 1
&& preg_match( Regex::BIDI_STEP_4_EN, $label ) === 1
) {
$this->info->setInvalidBidiDomain();
return;
}
return;
}
// We are a LTR label
// Step 1. The first character must be a character with Bidi property L, R, or AL.
// If it has the L property, it is an LTR label.
if ( preg_match( Regex::BIDI_STEP_1_LTR, $label ) !== 1 ) {
$this->info->setInvalidBidiDomain();
return;
}
// Step 5. In an LTR label, only characters with the Bidi properties L, EN,
// ES, CS, ET, ON, BN, or NSM are allowed.
if ( preg_match( Regex::BIDI_STEP_5, $label ) === 1 ) {
$this->info->setInvalidBidiDomain();
return;
}
// Step 6.In an LTR label, the end of the label must be a character with Bidi property L or
// EN, followed by zero or more characters with Bidi property NSM.
if ( preg_match( Regex::BIDI_STEP_6, $label ) !== 1 ) {
$this->info->setInvalidBidiDomain();
return;
}
}
}
@@ -0,0 +1,251 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Rowbot\Idna\Test;
use ReflectionClass;
use VendorPrefix\Rowbot\Idna\Idna;
use function array_filter;
use function array_flip;
use function is_array;
use function sprintf;
use function strncmp;
use const ARRAY_FILTER_USE_KEY;
class IdnaV2Test extends IdnaV2TestCase {
private const DEFAULT_OPTIONS = [
'CheckHyphens' => true,
'CheckBidi' => true,
'CheckJoiners' => true,
'UseSTD3ASCIIRules' => true,
'Transitional_Processing' => false,
'VerifyDnsLength' => true,
];
/**
* @var array<int, string>
*/
protected static $errorMap;
public static function setUpBeforeClass(): void {
if ( isset( self::$errorMap ) ) {
return;
}
$reflection = new ReflectionClass( Idna::class );
$errors = array_filter( $reflection->getConstants(), static function ( string $name ): bool {
return strncmp( $name, 'ERROR_', 6 ) === 0;
}, ARRAY_FILTER_USE_KEY );
self::$errorMap = array_flip( $errors );
}
/**
* @return array<int, array<int, string>>
*/
public function getData(): array {
return $this->loadTestData( Idna::UNICODE_VERSION );
}
/**
* @dataProvider getData
*/
public function testToUnicode(
string $source,
string $toUnicode,
string $toUnicodeStatus,
string $toAsciiN,
string $toAsciiNStatus,
string $toAsciiT,
string $toAsciiTStatus
): void {
[
$toUnicode,
$toUnicodeStatus,
$toAsciiN,
$toAsciiNStatus,
$toAsciiT,
$toAsciiTStatus,
] = $this->translate( $source, $toUnicode, $toUnicodeStatus, $toAsciiN, $toAsciiNStatus, $toAsciiT, $toAsciiTStatus );
$result = Idna::toUnicode( $source, self::DEFAULT_OPTIONS );
self::assertSame( $toUnicode, $result->getDomain() );
if ( $toUnicodeStatus === [] ) {
self::assertFalse( $result->hasErrors(), sprintf(
'Expected no errors, but found %s.',
$this->containedErrors( $result->getErrors() )
) );
} else {
self::assertTrue( $result->hasErrors(), sprintf(
'Expected to find %s, but found %s',
$this->expectedErrors( $toUnicodeStatus ),
$this->containedErrors( $result->getErrors() )
) );
}
}
/**
* @dataProvider getData
*/
public function testToAsciiNonTransitional(
string $source,
string $toUnicode,
string $toUnicodeStatus,
string $toAsciiN,
string $toAsciiNStatus,
string $toAsciiT,
string $toAsciiTStatus
): void {
[
$toUnicode,
$toUnicodeStatus,
$toAsciiN,
$toAsciiNStatus,
$toAsciiT,
$toAsciiTStatus,
] = $this->translate( $source, $toUnicode, $toUnicodeStatus, $toAsciiN, $toAsciiNStatus, $toAsciiT, $toAsciiTStatus );
$result = Idna::toAscii( $source, self::DEFAULT_OPTIONS );
if ( $toAsciiNStatus === [] ) {
self::assertSame( $toAsciiN, $result->getDomain() );
self::assertFalse( $result->hasErrors(), sprintf(
'Expected no errors, but found %s.',
$this->containedErrors( $result->getErrors() )
) );
} else {
self::assertTrue( $result->hasErrors(), sprintf(
'Expected %s, but found no errors.',
$this->expectedErrors( $toAsciiTStatus )
) );
}
}
/**
* @dataProvider getData
*/
public function testToAsciiTransitional(
string $source,
string $toUnicode,
string $toUnicodeStatus,
string $toAsciiN,
string $toAsciiNStatus,
string $toAsciiT,
string $toAsciiTStatus
): void {
[
$toUnicode,
$toUnicodeStatus,
$toAsciiN,
$toAsciiNStatus,
$toAsciiT,
$toAsciiTStatus,
] = $this->translate( $source, $toUnicode, $toUnicodeStatus, $toAsciiN, $toAsciiNStatus, $toAsciiT, $toAsciiTStatus );
$options = self::DEFAULT_OPTIONS;
$options['Transitional_Processing'] = true;
$result = Idna::toAscii( $source, $options );
// There is currently a bug in the test data, where it is expected that the following 2
// source strings result in an empty string. However, due to the way the test files are setup
// it currently isn't possible to represent an empty string as an expected value. So, we
// skip these 2 problem tests. I have notified the Unicode Consortium about this and they
// have passed the information along to the spec editors.
if ( $source === "\u{200C}" || $source === "\u{200D}" ) {
$toAsciiT = '';
}
if ( $toAsciiTStatus === [] ) {
self::assertSame( $toAsciiT, $result->getDomain() );
self::assertFalse( $result->hasErrors(), sprintf(
'Expected no errors, but found %s.',
$this->containedErrors( $result->getErrors() )
) );
} else {
self::assertTrue( $result->hasErrors(), sprintf(
'Expected %s, but found no errors.',
$this->expectedErrors( $toAsciiTStatus )
) );
}
}
public function assertErrors( array $expectedErrors, int $errors ): void {
foreach ( $expectedErrors as $errorCode ) {
if ( is_array( $errorCode ) ) {
self::assertTrue( $this->matchErrors( $errorCode, $errors ) );
continue;
}
self::assertTrue(
( $errors & $errorCode ) !== 0,
sprintf(
'Expected %s (%d), but only found %s.',
self::$errorMap[ $errorCode ],
$errorCode,
$this->containedErrors( $errors )
)
);
}
}
public function expectedErrors( array $expectedErrors ): string {
$message = '';
foreach ( $expectedErrors as $i => $errorCode ) {
if ( is_array( $errorCode ) ) {
$message .= '(';
foreach ( $errorCode as $j => $error ) {
if ( $j > 0 ) {
$message .= ' OR ';
}
$message .= sprintf( '%s (%d)', self::$errorMap[ $error ], $error );
}
$message .= ')';
} else {
if ( $i > 0 ) {
$message .= ' | ';
}
$message .= sprintf( '%s (%d)', self::$errorMap[ $errorCode ], $errorCode );
}
}
return $message;
}
public function containedErrors( int $errors ): string {
if ( $errors === 0 ) {
return 'no errors';
}
$out = '';
$count = 0;
foreach ( self::$errorMap as $code => $name ) {
if ( ( $errors & $code ) !== 0 ) {
if ( $count ++ > 0 ) {
$out .= ' | ';
}
$out .= sprintf( '%s (%d)', $name, $code );
}
}
return $out;
}
public function matchErrors( array $potentialErrors, int $errors ): bool {
foreach ( $potentialErrors as $error ) {
if ( ( $errors & $error ) !== 0 ) {
return true;
}
}
return false;
}
}
@@ -0,0 +1,212 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Rowbot\Idna\Test;
use GuzzleHttp\Client;
use PHPUnit\Framework\TestCase;
use VendorPrefix\Psr\Http\Message\ResponseInterface;
use VendorPrefix\Rowbot\Idna\Idna;
use RuntimeException;
use VendorPrefix\Symfony\Component\Cache\Adapter\FilesystemAdapter;
use function array_map;
use function count;
use function explode;
use function in_array;
use function preg_last_error;
use function preg_match_all;
use function sprintf;
use const DIRECTORY_SEPARATOR;
use const PREG_NO_ERROR;
class IdnaV2TestCase extends TestCase {
private const ERROR_CODE_MAP = [
'P1' => Idna::ERROR_DISALLOWED,
'P4' => [
Idna::ERROR_EMPTY_LABEL,
Idna::ERROR_DOMAIN_NAME_TOO_LONG,
Idna::ERROR_LABEL_TOO_LONG,
Idna::ERROR_PUNYCODE,
],
'V1' => Idna::ERROR_INVALID_ACE_LABEL,
'V2' => Idna::ERROR_HYPHEN_3_4,
'V3' => [ Idna::ERROR_LEADING_HYPHEN, Idna::ERROR_TRAILING_HYPHEN ],
'V4' => Idna::ERROR_LABEL_HAS_DOT,
'V5' => Idna::ERROR_LEADING_COMBINING_MARK,
'V6' => Idna::ERROR_DISALLOWED,
// V7 and V8 are handled by C* and B* respectively.
'A3' => Idna::ERROR_PUNYCODE,
'A4_1' => Idna::ERROR_DOMAIN_NAME_TOO_LONG,
'A4_2' => [ Idna::ERROR_EMPTY_LABEL, Idna::ERROR_LABEL_TOO_LONG ],
'B1' => Idna::ERROR_BIDI,
'B2' => Idna::ERROR_BIDI,
'B3' => Idna::ERROR_BIDI,
'B4' => Idna::ERROR_BIDI,
'B5' => Idna::ERROR_BIDI,
'B6' => Idna::ERROR_BIDI,
'C1' => Idna::ERROR_CONTEXTJ,
'C2' => Idna::ERROR_CONTEXTJ,
// ContextO isn't tested here.
// 'C3' => Idna::ERROR_CONTEXTO_PUNCTUATION,
// 'C4' => Idna::ERROR_CONTEXTO_PUNCTUATION,
// 'C5' => Idna::ERROR_CONTEXTO_PUNCTUATION,
// 'C6' => Idna::ERROR_CONTEXTO_PUNCTUATION,
// 'C7' => Idna::ERROR_CONTEXTO_PUNCTUATION,
// 'C8' => Idna::ERROR_CONTEXTO_DIGITS,
// 'C9' => Idna::ERROR_CONTEXTO_DIGITS,
'X4_2' => Idna::ERROR_EMPTY_LABEL,
'X3' => Idna::ERROR_EMPTY_LABEL,
];
private const BASE_URI = 'https://www.unicode.org/Public/idna/';
private const TEST_FILE = 'IdnaTestV2.txt';
private const CACHE_TTL = 86400 * 7; // 7 DAYS
private const TEST_DATA_DIR = __DIR__ . DIRECTORY_SEPARATOR . 'data';
/**
* @return array<int, array<int, string>>
*/
public function loadTestData( string $version ): array {
$cache = new FilesystemAdapter(
'unicode-idna-test-data',
self::CACHE_TTL,
self::TEST_DATA_DIR
);
$testData = $cache->getItem( $version );
if ( $testData->isHit() ) {
return $testData->get();
}
$client = new Client( [
'base_uri' => self::BASE_URI,
] );
$response = $client->request( 'GET', $version . '/' . self::TEST_FILE );
if ( $response->getStatusCode() >= 400 ) {
throw new RuntimeException( sprintf(
'Got status code %d trying to retrieve %s for Unicode version %s.',
$response->getStatusCode(),
self::TEST_FILE,
$version
) );
}
$data = $this->processResponse( $response );
$testData->set( $data );
$cache->save( $testData );
return $data;
}
/**
* @return array<int, array<int, string>>
*/
private function processResponse( ResponseInterface $response ): array {
$output = [];
foreach ( explode( "\n", (string) $response->getBody() ) as $line ) {
// Ignore empty lines and comments.
if ( $line === '' || $line[0] === '#' ) {
continue;
}
[ $data ] = explode( '#', $line );
$columns = array_map( '\trim', explode( ';', $data ) );
assert( count( $columns ) === 7 );
$output[] = $columns;
}
return $output;
}
/**
* @param array<int, int|array<int, int>> $inherit
*
* @return array<int, int|array<int, int>>
*/
private function resolveErrorCodes( string $statusCodes, array $inherit, array $ignore ): array {
if ( $statusCodes === '' ) {
return $inherit;
}
if ( $statusCodes === '[]' ) {
return [];
}
$matchCount = preg_match_all( '/[PVUABCX][0-9](?:_[0-9])?/', $statusCodes, $matches );
if ( preg_last_error() !== PREG_NO_ERROR ) {
throw new RuntimeException();
}
if ( $matchCount === 0 ) {
throw new RuntimeException();
}
$errors = [];
foreach ( $matches[0] as $match ) {
if ( $match[0] === 'U' || in_array( $match, $ignore, true ) ) {
continue;
}
if ( ! isset( self::ERROR_CODE_MAP[ $match ] ) ) {
throw new RuntimeException( sprintf( 'Unhandled error code %s.', $match ) );
}
$errors[] = self::ERROR_CODE_MAP[ $match ];
}
return $errors;
}
/**
* @return array{
* 0: string,
* 1: array<int, int|array<int, int>>,
* 2: string,
* 3: array<int, int|array<int, int>>,
* 4: string,
* 5: array<int, int|array<int, int>>
* }
*/
public function translate(
string $source,
string $toUnicode,
string $toUnicodeStatus,
string $toAsciiN,
string $toAsciiNStatus,
string $toAsciiT,
string $toAsciiTStatus,
array $ignore = []
): array {
if ( $toUnicode === '' ) {
$toUnicode = $source;
}
if ( $toAsciiN === '' ) {
$toAsciiN = $toUnicode;
}
if ( $toAsciiT === '' ) {
$toAsciiT = $toAsciiN;
}
$toUnicodeStatus = $this->resolveErrorCodes( $toUnicodeStatus, [], $ignore );
$toAsciiNStatus = $this->resolveErrorCodes( $toAsciiNStatus, $toUnicodeStatus, $ignore );
$toAsciiTStatus = $this->resolveErrorCodes( $toAsciiTStatus, $toAsciiNStatus, $ignore );
return [
$toUnicode,
$toUnicodeStatus,
$toAsciiN,
$toAsciiNStatus,
$toAsciiT,
$toAsciiTStatus,
];
}
}
@@ -0,0 +1,32 @@
# Changelog
## [Unreleased]
## [1.0.4] - 2024-05-02
### Fixed
- Fix implicit nullable deprecation warning for PHP 8.4
## [1.0.3] - 2022-01-10
### Changed
- Update PHPstan to 1.0
- Switched to GitHub Actions
## [1.0.2] - 2020-07-15
### Added
- Minor performance improvements
## [1.0.1] - 2020-06-16
### Fixed
- When calling `Punycode::decode()`, the case flags array would fail to populate when given an empty array.
## [1.0.0] - 2020-06-09
- Initial release
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2020 Trevor Rowbotham
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,83 @@
# Punycode
[![Software License](https://img.shields.io/github/license/TRowbotham/punycode?style=flat-square)](https://github.com/TRowbotham/punycode/blob/master/LICENSE)
[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/TRowbotham/punycode/Tests?style=flat-square)](https://travis-ci.com/github/TRowbotham/punycode)
[![Code Coverage](https://img.shields.io/codecov/c/github/TRowbotham/punycode/master?style=flat-square)](https://codecov.io/gh/TRowbotham/punycode)
[![PHP Version](https://img.shields.io/packagist/v/rowbot/punycode?style=flat-square)](https://packagist.org/packages/rowbot/punycode)
[![Total Downloads](https://img.shields.io/packagist/dt/rowbot/punycode?style=flat-square)](https://packagist.org/packages/rowbot/punycode)
An implementation of RFC 3492 Punycode in PHP, based on the sample implementation in [Appendix C](https://tools.ietf.org/html/rfc3492#appendix-C).
This is NOT a substitue for `idn_to_ascii` and `idn_to_utf8`.
## Requirements
- PHP 7.1+
## Installation
```bash
composer require rowbot/punycode
```
## API
### Punycode::decode(string $input, int $outLength = null, array &$caseFlags = [])
The `Punycode::decode()` method takes an ASCII encoded string and decodes it to a UTF-8 encoded
string. Optionally, the second parameter can be specified to place a limit on the size of the
returned string.
#### Parameters
- `$input` - An ASCII encoded punycode string to convert to a UTF-8 encoded string.
- `$outLength` - A positive integer representing the maximum length, in code points, of the resulting
output string. Defaults to 2,147,483,647.
- `$caseFlags` - An array, which will have the case flag of each character inserted into it.
#### Throws
- `\VendorPrefix\Rowbot\Punycode\Exception\OutputSizeExceededException` - If the size of the output string
exceeds the maximum size specified.
- `\VendorPrefix\Rowbot\Punycode\Exception\OverflowException` - If integer overflow occurs.
- `\VendorPrefix\Rowbot\Punycode\Exception\InvalidInputException` - If input contains non-ASCII bytes or mapping
a code point to a digit fails.
```php
use VendorPrefix\Rowbot\Punycode\Punycode;
try {
echo Punycode::decode('Hello-Another-Way--fc4qua05auwb3674vfr0b'); // Hello-Another-Way-それぞれの場所
} catch (\VendorPrefix\Rowbot\Punycode\Exception\PunycodeException $e) {
echo 'An error occured!';
}
```
### Punycode::encode(string $input, int $outLength = null, array $caseFlags = [])
The `Punycode::encode()` method takes a UTF-8 encoded string and converts it into an ASCII encoded
punycode string. Optionally, the second parameter can be specified to place a limit on the size of
the returned string.
#### Parameters
- `$input` - A UTF-8 encoded string to convert to punycode.
- `$outLength` - A positive integer representing the maximum length, in code points, of the resulting
output string. Defaults to 2,147,483,647.
- `$caseFlags` - An array of bools where true indicates that the character should be uppercase and
false indicates that it should be lowercase. This only affects ASCII characters `[a-zA-Z]`.
#### Throws
- `\VendorPrefix\Rowbot\Punycode\Exception\OutputSizeExceededException` - If the size of the output string
exceeds the maximum size specified.
- `\VendorPrefix\Rowbot\Punycode\Exception\OverflowException` - If integer overflow occurs.
```php
use VendorPrefix\Rowbot\Punycode\Punycode;
try {
echo Punycode::encode('Hello-Another-Way-それぞれの場所'); // Hello-Another-Way--fc4qua05auwb3674vfr0b
} catch (\VendorPrefix\Rowbot\Punycode\Exception\PunycodeException $e) {
echo 'An error occured!';
}
```
@@ -0,0 +1,42 @@
{
"name": "rowbot/punycode",
"description": "A Bootstring encoding of Unicode for Internationalized Domain Names in Applications (IDNA).",
"keywords": [
"punycode",
"rfc3492",
"rfc-3492"
],
"type": "library",
"license": "MIT",
"authors": [
{
"name": "Trevor Rowbotham",
"role": "Developer",
"homepage": "https://trowbotham.com"
}
],
"config": {
"sort-packages": true
},
"autoload": {
"psr-4": {
"VendorPrefix\\Rowbot\\Punycode\\": "src/"
}
},
"autoload-dev": {
"psr-4": {
"VendorPrefix\\Rowbot\\Punycode\\Test\\": "tests/"
}
},
"require": {
"php": ">=7.1"
},
"require-dev": {
"ext-mbstring": "*",
"phpstan/phpstan": "^1.2",
"phpstan/phpstan-deprecation-rules": "^1.0",
"phpstan/phpstan-strict-rules": "^1.0",
"phpunit/phpunit": "^7.0 || ^8.0 || ^9.0",
"squizlabs/php_codesniffer": "^3.5.1"
}
}
@@ -0,0 +1,8 @@
includes:
- vendor/phpstan/phpstan-strict-rules/rules.neon
- vendor/phpstan/phpstan-deprecation-rules/rules.neon
parameters:
level: max
paths:
- src
@@ -0,0 +1,20 @@
<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/5.7/phpunit.xsd"
bootstrap="vendor/autoload.php"
backupGlobals="false"
beStrictAboutCoversAnnotation="true"
beStrictAboutOutputDuringTests="true"
beStrictAboutTestsThatDoNotTestAnything="true"
beStrictAboutTodoAnnotatedTests="true"
verbose="true">
<testsuite name="default">
<directory suffix="Test.php">tests</directory>
</testsuite>
<filter>
<whitelist processUncoveredFilesFromWhitelist="true">
<directory suffix=".php">src</directory>
</whitelist>
</filter>
</phpunit>
@@ -0,0 +1,8 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Rowbot\Punycode\Exception;
class InvalidInputException extends PunycodeException {
}
@@ -0,0 +1,8 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Rowbot\Punycode\Exception;
class OutputSizeExceededException extends PunycodeException {
}
@@ -0,0 +1,8 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Rowbot\Punycode\Exception;
final class OverflowException extends PunycodeException {
}
@@ -0,0 +1,10 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Rowbot\Punycode\Exception;
use Exception;
class PunycodeException extends Exception {
}
@@ -0,0 +1,676 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Rowbot\Punycode;
use VendorPrefix\Rowbot\Punycode\Exception\InvalidInputException;
use VendorPrefix\Rowbot\Punycode\Exception\OutputSizeExceededException;
use VendorPrefix\Rowbot\Punycode\Exception\OverflowException;
use function array_map;
use function array_splice;
use function chr;
use function func_num_args;
use function implode;
use function intdiv;
use function ord;
use function str_split;
use function strlen;
use function strrpos;
/**
* @see https://tools.ietf.org/html/rfc3492
* @see https://github.com/bestiejs/punycode.js/blob/master/punycode.js
* @see https://github.com/unicode-org/icu/blob/master/icu4c/source/common/punycode.cpp
* @see https://github.com/unicode-org/icu/blob/master/icu4j/main/classes/core/src/com/ibm/icu/impl/Punycode.java
*/
final class Punycode {
private const BASE = 36;
private const TMIN = 1;
private const TMAX = 26;
private const SKEW = 38;
private const DAMP = 700;
private const INITIAL_BIAS = 72;
private const INITIAL_N = 128;
private const DELIMITER = '-';
private const MAX_INT = 2147483647;
/**
* Contains the numeric value of a basic code point (for use in representing integers) in the
* range 0 to BASE-1, or -1 if b is does not represent a value.
*
* @var array<int, int>
*/
private static $basicToDigit = [
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
26,
27,
28,
29,
30,
31,
32,
33,
34,
35,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
0,
1,
2,
3,
4,
5,
6,
7,
8,
9,
10,
11,
12,
13,
14,
15,
16,
17,
18,
19,
20,
21,
22,
23,
24,
25,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
0,
1,
2,
3,
4,
5,
6,
7,
8,
9,
10,
11,
12,
13,
14,
15,
16,
17,
18,
19,
20,
21,
22,
23,
24,
25,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
- 1,
];
/**
* @codeCoverageIgnore
*/
private function __construct() {
}
/**
* @see https://tools.ietf.org/html/rfc3492#section-6.1
*/
private static function adaptBias( int $delta, int $numPoints, bool $firstTime ): int {
// xxx >> 1 is a faster way of doing intdiv(xxx, 2)
$delta = $firstTime ? intdiv( $delta, self::DAMP ) : $delta >> 1;
$delta += intdiv( $delta, $numPoints );
$k = 0;
while ( $delta > ( ( self::BASE - self::TMIN ) * self::TMAX ) >> 1 ) {
$delta = intdiv( $delta, self::BASE - self::TMIN );
$k += self::BASE;
}
return $k + intdiv( ( self::BASE - self::TMIN + 1 ) * $delta, $delta + self::SKEW );
}
/**
* @see https://tools.ietf.org/html/rfc3492#section-6.2
*
* @param array<int, bool> $caseFlags
*/
public static function decode( string $input, ?int $outLength = null, array &$caseFlags = [] ): string {
$n = self::INITIAL_N;
$out = 0;
$i = 0;
$maxOut = $outLength ?? self::MAX_INT;
$bias = self::INITIAL_BIAS;
$lastDelimIndex = strrpos( $input, self::DELIMITER );
$b = $lastDelimIndex === false ? 0 : $lastDelimIndex;
$inputLength = strlen( $input );
$output = [];
$wantsCaseFlags = func_num_args() > 2;
if ( $b > $maxOut ) {
throw new OutputSizeExceededException();
}
$bytes = array_map( 'ord', str_split( $input ) );
for ( $j = 0; $j < $b; ++ $j ) {
if ( $bytes[ $j ] > 0x7F ) {
throw new InvalidInputException();
}
if ( $wantsCaseFlags ) {
$caseFlags[ $out ] = self::flagged( $bytes[ $j ] );
}
$output[ $out ++ ] = $input[ $j ];
}
if ( $b > 0 ) {
$b += 1;
}
for ( $in = $b; $in < $inputLength; ++ $out ) {
$oldi = $i;
$w = 1;
for ( $k = self::BASE; ; $k += self::BASE ) {
if ( $in >= $inputLength ) {
throw new InvalidInputException();
}
$digit = self::$basicToDigit[ $bytes[ $in ++ ] & 0xFF ];
if ( $digit < 0 ) {
throw new InvalidInputException();
}
if ( $digit > intdiv( self::MAX_INT - $i, $w ) ) {
throw new OverflowException();
}
$i += $digit * $w;
if ( $k <= $bias ) {
$t = self::TMIN;
} elseif ( $k >= $bias + self::TMAX ) {
$t = self::TMAX;
} else {
$t = $k - $bias;
}
if ( $digit < $t ) {
break;
}
$baseMinusT = self::BASE - $t;
if ( $w > intdiv( self::MAX_INT, $baseMinusT ) ) {
throw new OverflowException();
}
$w *= $baseMinusT;
}
$outPlusOne = $out + 1;
$bias = self::adaptBias( $i - $oldi, $outPlusOne, $oldi === 0 );
if ( intdiv( $i, $outPlusOne ) > self::MAX_INT - $n ) {
throw new OverflowException();
}
$n += intdiv( $i, $outPlusOne );
$i %= $outPlusOne;
if ( $out >= $maxOut ) {
throw new OutputSizeExceededException();
}
if ( $wantsCaseFlags ) {
array_splice( $caseFlags, $i, 0, [ self::flagged( $bytes[ $n - 1 ] ) ] );
}
array_splice( $output, $i ++, 0, [ self::encodeCodePoint( $n ) ] );
}
return implode( '', $output );
}
/**
* @see https://tools.ietf.org/html/rfc3492#section-6.3
*
* @param array<int, bool> $caseFlags
*/
public static function encode( string $input, ?int $outLength = null, array $caseFlags = [] ): string {
$n = self::INITIAL_N;
$delta = 0;
$out = 0;
$maxOut = $outLength ?? self::MAX_INT;
$bias = self::INITIAL_BIAS;
$inputLength = 0;
$output = '';
$codePoints = self::utf8Decode( $input );
foreach ( $codePoints as $j => $codePoint ) {
++ $inputLength;
if ( $codePoint < 0x80 ) {
if ( $maxOut - $out < 2 ) {
throw new OutputSizeExceededException();
}
$output .= isset( $caseFlags[ $j ] )
? self::encodeBasic( $codePoint, $caseFlags[ $j ] )
: chr( $codePoint );
++ $out;
}
}
$h = $out;
$b = $out;
if ( $b > 0 ) {
$output .= self::DELIMITER;
++ $out;
}
while ( $h < $inputLength ) {
$m = self::MAX_INT;
foreach ( $codePoints as $codePoint ) {
if ( $codePoint >= $n && $codePoint < $m ) {
$m = $codePoint;
}
}
if ( $m - $n > intdiv( self::MAX_INT - $delta, $h + 1 ) ) {
throw new OverflowException();
}
$delta += ( $m - $n ) * ( $h + 1 );
$n = $m;
foreach ( $codePoints as $j => $codePoint ) {
if ( $codePoint < $n && ++ $delta === 0 ) {
throw new OverflowException();
} elseif ( $codePoint === $n ) {
$q = $delta;
for ( $k = self::BASE; ; $k += self::BASE ) {
if ( $out >= $maxOut ) {
throw new OutputSizeExceededException();
}
if ( $k <= $bias ) {
$t = self::TMIN;
} elseif ( $k >= $bias + self::TMAX ) {
$t = self::TMAX;
} else {
$t = $k - $bias;
}
if ( $q < $t ) {
break;
}
$qMinusT = $q - $t;
$baseMinusT = self::BASE - $t;
$output .= self::encodeDigit( $t + ( $qMinusT ) % ( $baseMinusT ), false );
++ $out;
$q = intdiv( $qMinusT, $baseMinusT );
}
$output .= self::encodeDigit( $q, $caseFlags[ $j ] ?? false );
++ $out;
$bias = self::adaptBias( $delta, $h + 1, $h === $b );
$delta = 0;
++ $h;
}
}
++ $delta;
++ $n;
}
return $output;
}
private static function encodeBasic( int $codePoint, bool $flag ): string {
$codePoint -= ( $codePoint - 97 < 26 ? 1 : 0 ) << 5;
return chr( $codePoint + ( ( ! $flag && ( $codePoint - 65 < 26 ) ? 1 : 0 ) << 5 ) );
}
/**
* Takes a Unicode code point and encodes it. The return behavior is undefined if the given
* code point is outside the range 0..10FFFF.
*
* @see https://encoding.spec.whatwg.org/#utf-8-encoder
*/
private static function encodeCodePoint( int $codePoint ): string {
if ( $codePoint >= 0x00 && $codePoint <= 0x7F ) {
return chr( $codePoint );
}
$count = 0;
$offset = 0;
if ( $codePoint >= 0x0080 && $codePoint <= 0x07FF ) {
$count = 1;
$offset = 0xC0;
} elseif ( $codePoint >= 0x0800 && $codePoint <= 0xFFFF ) {
$count = 2;
$offset = 0xE0;
} elseif ( $codePoint >= 0x10000 && $codePoint <= 0x10FFFF ) {
$count = 3;
$offset = 0xF0;
}
$bytes = chr( ( $codePoint >> ( 6 * $count ) ) + $offset );
while ( $count > 0 ) {
$temp = $codePoint >> ( 6 * ( $count - 1 ) );
$bytes .= chr( 0x80 | ( $temp & 0x3F ) );
-- $count;
}
return $bytes;
}
private static function encodeDigit( int $d, bool $flag ): string {
return chr( $d + 22 + 75 * ( $d < 26 ? 1 : 0 ) - ( ( $flag ? 1 : 0 ) << 5 ) );
}
private static function flagged( int $codePoint ): bool {
return $codePoint - 65 < 26;
}
/**
* Takes a UTF-8 encoded string and converts it into a series of integer code points. Any
* invalid byte sequences will be replaced by a U+FFFD replacement code point.
*
* @see https://encoding.spec.whatwg.org/#utf-8-decoder
*
* @return array<int, int>
*/
private static function utf8Decode( string $input ): array {
$bytesSeen = 0;
$bytesNeeded = 0;
$lowerBoundary = 0x80;
$upperBoundary = 0xBF;
$codePoint = 0;
$codePoints = [];
$length = strlen( $input );
for ( $i = 0; $i < $length; ++ $i ) {
$byte = ord( $input[ $i ] );
if ( $bytesNeeded === 0 ) {
if ( $byte <= 0x7F ) {
$codePoints[] = $byte;
continue;
}
if ( $byte >= 0xC2 && $byte <= 0xDF ) {
$bytesNeeded = 1;
$codePoint = $byte & 0x1F;
} elseif ( $byte >= 0xE0 && $byte <= 0xEF ) {
if ( $byte === 0xE0 ) {
$lowerBoundary = 0xA0;
} elseif ( $byte === 0xED ) {
$upperBoundary = 0x9F;
}
$bytesNeeded = 2;
$codePoint = $byte & 0xF;
} elseif ( $byte >= 0xF0 && $byte <= 0xF4 ) {
if ( $byte === 0xF0 ) {
$lowerBoundary = 0x90;
} elseif ( $byte === 0xF4 ) {
$upperBoundary = 0x8F;
}
$bytesNeeded = 3;
$codePoint = $byte & 0x7;
} else {
$codePoints[] = 0xFFFD;
}
continue;
}
if ( $byte < $lowerBoundary || $byte > $upperBoundary ) {
$codePoint = 0;
$bytesNeeded = 0;
$bytesSeen = 0;
$lowerBoundary = 0x80;
$upperBoundary = 0xBF;
-- $i;
$codePoints[] = 0xFFFD;
continue;
}
$lowerBoundary = 0x80;
$upperBoundary = 0xBF;
$codePoint = ( $codePoint << 6 ) | ( $byte & 0x3F );
if ( ++ $bytesSeen !== $bytesNeeded ) {
continue;
}
$codePoints[] = $codePoint;
$codePoint = 0;
$bytesNeeded = 0;
$bytesSeen = 0;
}
// String unexpectedly ended, so append a U+FFFD code point.
if ( $bytesNeeded !== 0 ) {
$codePoints[] = 0xFFFD;
}
return $codePoints;
}
}
@@ -0,0 +1,200 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Rowbot\Punycode\Test;
use PHPUnit\Framework\TestCase;
use VendorPrefix\Rowbot\Punycode\Exception\InvalidInputException;
use VendorPrefix\Rowbot\Punycode\Exception\OutputSizeExceededException;
use VendorPrefix\Rowbot\Punycode\Punycode;
use function mb_strlen;
use function preg_match;
class PunycodeTest extends TestCase {
/**
* @see https://tools.ietf.org/html/rfc3492#section-7.1
*
* @return array<int, array<int, string>>
*/
public static function punycodeProvider(): array {
return [
[
'ليهمابتكلموشعربي؟',
'egbpdaj6bu4bxfgehfvwxn',
'Arabic (Egyptian)',
],
[
'他们为什么不说中文',
'ihqwcrb4cv8a8dqg056pqjye',
'Chinese (simplified)',
],
[
'他們爲什麽不說中文',
'ihqwctvzc91f659drss3x8bo0yb',
'Chinese (traditional)',
],
[
'Pročprostěnemluvíčesky',
'Proprostnemluvesky-uyb24dma41a',
'Czech',
],
[
'למההםפשוטלאמדבריםעברית',
'4dbcagdahymbxekheh6e0a7fei0b',
'Hebrew',
],
[
'यहलोगहिन्दीक्योंनहींबोलसकतेहैं',
'i1baa7eci9glrd9b2ae1bj0hfcgg6iyaf8o0a1dig0cd',
'Hindi (Devanagari)',
],
[
'なぜみんな日本語を話してくれないのか',
'n8jok5ay5dzabd5bym9f0cm5685rrjetr6pdxa',
'Japanese (kanji and hiragana)',
],
[
'세계의모든사람들이한국어를이해한다면얼마나좋을까',
'989aomsvi5e83db1d2a355cv1e0vak1dwrv93d5xbh15a0dt30a5jpsd879ccm6fea98c',
'Korean (Hangul syllables)',
],
[
'почемужеонинеговорятпорусски',
'b1abfaaepdrnnbgefbadotcwatmq2g4l',
'Russian (Cyrillic)',
],
[
'PorquénopuedensimplementehablarenEspañol',
'PorqunopuedensimplementehablarenEspaol-fmd56a',
'Spanish',
],
[
'TạisaohọkhôngthểchỉnóitiếngViệt',
'TisaohkhngthchnitingVit-kjcr8268qyxafd2f1b9g',
'Vietnamese',
],
[
'3年B組金八先生',
'3B-ww4c5e180e575a65lsy2b',
'',
],
[
'安室奈美恵-with-SUPER-MONKEYS',
'-with-SUPER-MONKEYS-pc58ag80a8qai00g7n9n',
'',
],
[
'Hello-Another-Way-それぞれの場所',
'Hello-Another-Way--fc4qua05auwb3674vfr0b',
'',
],
[
'ひとつ屋根の下2',
'2-u9tlzr9756bt3uc0v',
'',
],
[
'MajiでKoiする5秒前',
'MajiKoi5-783gue6qz075azm5e',
'',
],
[
'パフィーdeルンバ',
'de-jg4avhby1noc0d',
'',
],
[
'そのスピードで',
'd9juau41awczczp',
'',
],
[
'-> $1.00 <-',
'-> $1.00 <--',
'',
],
];
}
/**
* @dataProvider punycodeProvider
*/
public function testEncode( string $decoded, string $encoded, string $comment ): void {
self::assertSame( $encoded, Punycode::encode( $decoded ), $comment );
}
/**
* @dataProvider punycodeProvider
*/
public function testDecode( string $decoded, string $encoded, string $comment ): void {
self::assertSame( $decoded, Punycode::decode( $encoded ), $comment );
}
public function encodeMaxLengthDataProvider(): array {
return array_filter( $this->punycodeProvider(), static function ( array $data ): bool {
return mb_strlen( $data[1], 'utf-8' ) > 10;
} );
}
/**
* @dataProvider encodeMaxLengthDataProvider
*/
public function testEncodeMaxLength( string $decoded, string $encoded, string $comment ): void {
$this->expectException( OutputSizeExceededException::class );
Punycode::encode( $decoded, 10 );
}
/**
* @return array<int, array<int, string>>
*/
public function decodeMaxLengthDataProvider(): array {
return array_filter( $this->punycodeProvider(), static function ( array $data ): bool {
return mb_strlen( $data[0], 'utf-8' ) > 10;
} );
}
/**
* @dataProvider decodeMaxLengthDataProvider
*/
public function testDecodeMaxLength( string $decoded, string $encoded, string $comment ): void {
$this->expectException( OutputSizeExceededException::class );
Punycode::decode( $encoded, 10 );
}
/**
* @return array<int, array<int, string>>
*/
public function nonAsciiDataProvider(): array {
return array_filter( $this->punycodeProvider(), static function ( array $data ): bool {
return preg_match( '/[^\x00-\x7F]/', $data[0] ) === 1;
} ) + [
[ "abc\u{FFFD}", '', 'Mixed ASCII and non-ASCII' ],
];
}
/**
* @dataProvider nonAsciiDataProvider
*/
public function testDecodeOnlyAcceptsAscii( string $decoded, string $encoded, string $comment ): void {
$this->expectException( InvalidInputException::class );
Punycode::decode( $decoded );
}
public function testCaseFlags(): void {
$c = [ true, true, true ];
$e = Punycode::encode( 'abc', null, $c );
self::assertSame( 'ABC-', $e );
$c = [ false, false, false ];
$d = Punycode::decode( $e, null, $c );
self::assertSame( [ true, true, true ], $c );
self::assertSame( 'ABC', $d );
$c = [];
$d = Punycode::decode( $e, null, $c );
self::assertSame( [ true, true, true ], $c );
self::assertSame( 'ABC', $d );
}
}
@@ -0,0 +1,302 @@
# Changelog
## [Unreleased]
## [4.0.0] - 2024-06-20
### Added
- Performance improvements
- Validation error logging
- `\VendorPrefix\Rowbot\URL\URL` and `\VendorPrefix\Rowbot\URL\URLSearchParams` now implement `\Stringable`
- `\VendorPrefix\Rowbot\URL\URLSearchParams` constructor now has a native typehint of `array|object|string`
- `\VendorPrefix\Rowbot\URL\URLSearchParams` now has a `size` getter per [whatwg/url#734](https://github.com/whatwg/url/pull/734)
- `\VendorPrefix\Rowbot\URL\URLSearchParams` now also implements `\Countable`
- Added `\VendorPrefix\Rowbot\URL\URL::canParse()`, which returns a boolean if parsing was successful, per [whatwg/url#713](https://github.com/whatwg/url/issues/713) and [whatwg/url#763](https://github.com/whatwg/url/pull/763)
- Add value parameter to `\VendorPrefix\Rowbot\URL\URLSearchParams::has()` and `\VendorPrefix\Rowbot\URL\URLSearchParams::delete()` per [whatwg/url#335](https://github.com/whatwg/url/issues/335) and [whatwg/url#735](https://github.com/whatwg/url/pull/735)
- Added `\VendorPrefix\Rowbot\URL\URL::parse()`, which will return the parsed URL or null on failure, avoiding needing a `try` statement per [whatwg/url#372](https://github.com/whatwg/url/issues/372) and [whatwg/url#825](https://github.com/whatwg/url/pull/825)
### Changed
- Bump minimum PHP version to 8.1
- Lone surrogate code points are no longer treated differently from other invalid code points
- `\VendorPrefix\Rowbot\URL\String\Exception\UConverterException` has been renamed to `\VendorPrefix\Rowbot\URL\String\Exception\EncodingException`
- Moved 32-bit tests to GitHub Actions from Appveyor
- `\VendorPrefix\Rowbot\URL\URL`'s $url and $base parameters now also accept `\Stringable`
- `\VendorPrefix\Rowbot\URL\URLSearchParams::current()` now returns `null` when the iterator is invalid instead of `['', '']`, which better matches the expected behavior
- Ensure opaque paths can round trip from the API [whatwg/url#651](https://github.com/whatwg/url/issues/651) [whatwg/url#728](https://github.com/whatwg/url/pull/728)
- Blob URL's with an inner non-http(s) URL now returns an opaque origin per [whatwg/url#770](https://github.com/whatwg/url/issues/770) and [whatwg/url#771](https://github.com/whatwg/url/pull/771)
### Removed
- Removed `\VendorPrefix\Rowbot\URL\Exception\JsonException` in favor of `\JsonException`
### Internals
- Removed class `\VendorPrefix\Rowbot\URL\String\IDLString`
- Added method `\VendorPrefix\Rowbot\URL\String\Utf8String::scrub()`
- Added method `\VendorPrefix\Rowbot\URL\String\Utf8String::fromUnsafe()`
- Moved method `\VendorPrefix\Rowbot\URL\String\AbstractUSVString::transcode()` to `\VendorPrefix\Rowbot\URL\String\Utf8String`
- Removed method `\VendorPrefix\Rowbot\URL\String\Exception\RegexException::getNameFromLastCode()`
- All objects with a `__toString()` method now implement `\Stringable`
- Added native union typehints where possible
- `\VendorPrefix\Rowbot\URL\Origin` is now an interface
- Added class `\VendorPrefix\Rowbot\URL\Component\TupleOrigin` which implements `\VendorPrefix\Rowbot\URL\Origin`
- Added class `\VendorPrefix\Rowbot\URL\Component\OpaqueOrigin` which implements `\VendorPrefix\Rowbot\URL\Origin`
- `\VendorPrefix\Rowbot\URL\Component\PathListInterface` renamed to `\VendorPrefix\Rowbot\URL\PathInterface`
- Added class `\VendorPrefix\Rowbot\URL\Component\OpaquePath` which implements `\VendorPrefix\Rowbot\URL\PathInterface`
- `\VendorPrefix\Rowbot\URL\Component\Path` was renamed to `\VendorPrefix\Rowbot\URL\Component\PathSegment`
- `\VendorPrefix\Rowbot\URL\State\CannotBeABaseUrlPathState` was renamed to `\VendorPrefix\Rowbot\URL\State\OpaquePathState`
- Removed property `\VendorPrefix\Rowbot\URL\URLRecord::$cannotBeABaseUrl`
- Adopted the specs new percent encoding model
- Removed const `\VendorPrefix\Rowbot\URL\String\CodePoint::C0_CONTROL_PERCENT_ENCODE_SET`
- Removed const `\VendorPrefix\Rowbot\URL\String\CodePoint::FRAGMENT_PERCENT_ENCODE_SET`
- Removed const `\VendorPrefix\Rowbot\URL\String\CodePoint::PATH_PERCENT_ENCODE_SET`
- Removed const `\VendorPrefix\Rowbot\URL\String\CodePoint::USERINFO_PERCENT_ENCODE_SET`
- Removed method `\VendorPrefix\Rowbot\URL\String\CodePoint::utf8PercentEncode()`
- Added enum `\VendorPrefix\Rowbot\URL\String\EncodeSet`
- Added class `\VendorPrefix\Rowbot\URL\String\PercentEncoder`
- `\VendorPrefix\Rowbot\URL\Component\Host\HostParser` methods are no longer static
- `\VendorPrefix\Rowbot\URL\String\StringListInterface` extends `\IteratorAggregate` instead of `\Iterator`
- `\VendorPrefix\Rowbot\URL\Component\QueryList` now implements `\Countable`
- Added enum `\VendorPrefix\Rowbot\URL\State\StatusCode`
- `\VendorPrefix\Rowbot\URL\State\State` now has a return type of `\VendorPrefix\Rowbot\URL\State\StatusCode` instead of `int`
- Removed const `\VendorPrefix\Rowbot\URL\State\State::RETURN_OK`
- Removed const `\VendorPrefix\Rowbot\URL\State\State::RETURN_CONTINUE`
- Removed const `\VendorPrefix\Rowbot\URL\State\State::RETURN_BREAK`
- Removed const `\VendorPrefix\Rowbot\URL\State\State::RETURN_FAILURE`
## [3.1.7] - 2022-08-26
### Fixed
- Detection of windows drive letters
## [3.1.6] - 2022-08-16
### Changed
- Forbid C0 control code points and U+007F DEL code point in non-opaque domain names per [whatwg/url#685](https://github.com/whatwg/url/pull/685)
## Fixed
- Fix parsing IPv4-mapped IPv6 addresses due to wrong logical condition
## [3.1.5] - 2022-01-10
### Changed
- Upgraded to PHPStan 1.0
### Fixed
- Initialization of `URLSearchParams` using an object now behaves the same as when using and iterator or string
## [3.1.4] - 2021-07-27
### Added
- Support for PHP 8.1
### Changed
- Make the `URL::$hostname` setter do nothing if the host name contains a ":" per [whatwg/url#601](https://github.com/whatwg/url/issues/601) [whatwg/url#604](https://github.com/whatwg/url/pull/604)
- Reject non-IPv4 hostnames that end in numbers per [whatwg/url#560](https://github.com/whatwg/url/issues/560) [whatwg/url#619](https://github.com/whatwg/url/pull/619)
### Fixed
- Prevent the pathname setter from erasing the path of path-only URLs [whatwg/url#581](https://github.com/whatwg/url/issues/581) [whatwg/url#582](https://github.com/whatwg/url/pull/582)
## [3.1.3] - 2021-05-11
### Fixed
- File URL reparse bug with percent encoded windows drive letter [whatwg/url#589](https://github.com/whatwg/url/pull/589)
### Changed
- Switched to GitHub Actions for CI
- Minimum PHPUnit version is now 7.5
## [3.1.2] - 2021-02-11
### Added
- Performance improvements
- Test on PHP 8 release in CI
## [3.1.1] - 2020-10-17
### Added
- Support for `brick/math` ^0.9
### Changed
- Serializing non-special URLs is now idempotent per [whatwg/url#505](https://github.com/whatwg/url/pull/505)
- Changes to file URL path normalization per [whatwg/url#544](https://github.com/whatwg/url/pull/544).
## [3.1.0] - 2020-07-15
### Added
- Added test coverage on Windows 32-bit.
- Dependency on `rowbot/idna` to support international domain names without `ext-intl`.
### Changed
- `URLSearchParams::sort()` now correctly sorts by code units instead of trying to fake it using code points.
- Null bytes are now percent encoded in fragments instead of being ignored per [whatwg/url#440](https://github.com/whatwg/url/issues/440).
- Domain names of URLs with special schemes can no longer be an empty string per [whatwg/url#492](https://github.com/whatwg/url/pull/492) and [whatwg/url#497](https://github.com/whatwg/url/pull/497).
- Host names now also forbid the use of the `<`, `>`, and `^` code points per [whatwg/url#458](https://github.com/whatwg/url/issues/458).
### Fixed
- Incorrect output encoding used when encoding was overriden to be "replacement", "utf-16", "utf-16le", or "utf-16be".
- `ext-json` is now correctly listed as a dependency.
### Removed
- Dependency on `ext-intl` and `lib-ICU`.
## [3.0.1] - 2020-02-29
### Added
- Improved portability and 32-bit PHP support.
- Dependency on `brick/math` to support 32-bit versions of PHP.
### Removed
- Removed `ext-gmp` as a dependency.
## [3.0.0] - 2020-02-11
The majority of this library was rewritten in this update, but the public API has remain unchanged. This should make for a relatively painless upgrade.
### Added
- Installation requirement of ICU >= 4.6 to assist with [#6](https://github.com/TRowbotham/URL-Parser/issues/6)
- Support for PHPUnit ^8.0 and ^9.0.
- More test coverage.
- Support for symfony/cache ^5.0.
### Changed
- "gopher" was removed from the list of special schemes per [whatwg/url#453](https://github.com/whatwg/url/pull/453) and [whatwg/url#454](https://github.com/whatwg/url/pull/454).
- Coding style has been updated for PSR-12.
- Non-iterable objects passed to the `URLSearchParams` constructor now have their properties iterated over using `\ReflectionObject::getProperties()` rather than directly. There should not be any change in behavior.
- Removed artificial limitation when passing a sequence of sequences to the `URLSearchParams` constructor that required the non-array sub-sequences to implement the `\ArrayAccess` interface.
- Note that sub-sequences must still be countable and only contain exactly 2 items.
- This broadens the type of sequences that can be supplied from `iterable<mixed, array{0: string, 1: string}>` to `iterable<mixed, iterable<mixed, stringable>>`, where `stringable` is a scalar value or an object with the `__toString()` method.
- `URLSearchParams` now throws a `\VendorPrefix\Rowbot\URL\Exception\TypeError` instead of a `\InvalidArgument` exception to match browsers when passed an iterable that does not solely contain other iterables that are countable.
- JSON encoding the `URL` object will now throw a `\VendorPrefix\Rowbot\URL\Exception\JsonException` when JSON encoding fails.
### Fixed
- Documentaion errors.
- Restores expected string conversion behavior on systems using an ICU version >= 60.1 ([#7](https://github.com/TRowbotham/URL-Parser/issues/6)).
- `Origin::getEffectiveDomain()` was incorrectly returning the string `"null"` instead of the actual value `null` when the origin was an opaque origin.
### Removed
- `phpstan/phpstan` and associated packages are no longer a dev dependency and is now only run in CI.
- No longer depends on `ext-ctype`, which was an unlisted dependency.
- `php-coveralls/php-coveralls` is no longer a dev dependency. The project has moved to Codecov instead.
- `squizlabs/php_codesniffer` is no longer a dev dependency and is only run in CI now.
## [2.0.3] - 2019-08-13
### Fixed
- "%2e%2E" and "%2E%2e" were not properly detected as percent encoded double dot path segments.
## [2.0.2] - 2019-04-28
### Added
- PHP 7.4 compatibility
- Sped up IPv6 address serialization by removing some unncessary type casting.
## [2.0.1] - 2019-04-15
### Fixed
- Loading cached test data failed when using newer versions of the symfony/cache component.
## [2.0.0] - 2018-12-08
### Added
- Tests now automatically pull the latest data directly from the Web Platform Tests repository - thanks [@nyamsprod](https://github.com/nyamsprod)
### Changed
- The minimum required PHP version is now 7.1.
- Testing environment updated for PHP 7.1 - thanks [@nyamsprod](https://github.com/nyamsprod)
- Native typehints are now used. This which means that an `\TypeError` is now thrown instead of an `\InvalidArgumentException` when a value with an incorrect type is passed.
- `\VendorPrefix\Rowbot\URL\Exception\TypeError` and `\VendorPrefix\Rowbot\URL\Exception\InvalidParserState` now inherit from `\VendorPrefix\Rowbot\URL\Exception\URLException`
## [1.1.1] - 2018-08-15
### Added
- Sped up `URLSearchParams::has()` when the string does not exist in the list.
- TravisCI automation for tests and code coverage.
### Fixed
- The query string sorting algorithm now correctly sorts by code units instead of code points.
## [1.1.0] - 2018-06-21
### Added
- Updated documentation
- Updated tests
### Changed
- Only scalar values (bool, float, int, string) and objects with a `__toString()` method are considered as valid input now for methods and properties that only accept strings. This matches what PHP's string type hint would allow, allowing for an easier upgrade path when adding native type hints in the future.
- A `null` value is no longer considered valid input and will cause an `\InvalidArgumentException` to be thrown. Previously, this was converted to the string `"null"`.
- A `resource` value such as that returned by a call to `fopen()` is no longer considered valid input and will cause an `\InvalidArgumentException` to be thrown. This was previously casted to a string resulting in something like `"Resource id #1"`.
- Previously, the values `true` and `false` were converted to the strings `"true"` and `"false"`. This is no longer the case. They now are now simply cast to a string resulting in the values `"1"` and `""` respectively.
- Passing an `iterable` that does not solely contain other `iterables` to the `URLSearchParams` constructor now causes it to throw an `\InvalidArgumentException`.
- Trying to access an invalid property on the `URL` object will now throw an `\InvalidArgumentException` to help catch typos.
## [1.0.3] - 2018-06-19
### Added
- Sped up serialization of IPv6 addresses
- Slightly better handling of non-UTF-8 encoded text when parsing query strings.
- A bunch of missing `use` import statements
- Updated tests and test data.
### Changed
- URLs with [special schemes](https://url.spec.whatwg.org/#special-scheme) now percent encode `'` characters in the query string.
- The application/x-www-form-urlencoded parser now only handles UTF-8 encoded text.
## [1.0.2] - 2018-02-28
### Changed
- Trying to set `URL::searchParams` directly will now throw a `\VendorPrefix\Rowbot\URL\Exception\TypeError`
- Passing invalid input will throw an `\InvalidArgumentException`
- Malformed byte sequences will now get fixed up with `\u{FFFD}` replacement characters.
- `URLSearchParams` now implements `\Iterator` instead of `\IteratorAggregate` to match test expectations.
### Fixed
- The last few failing tests are now passing with the exception of 3 errors as a result of PHP bug [72506](https://bugs.php.net/bug.php?id=72506)
## [1.0.1] - 2018-02-22
### Added
- MIT License
## [1.0.0] - 2018-02-22
- Initial Release!
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2018 Trevor Rowbotham
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,255 @@
# URL-Parser
[![GitHub](https://img.shields.io/github/license/TRowbotham/URL-Parser.svg?style=flat-square)](https://github.com/TRowbotham/URL-Parser/blob/master/LICENSE)
[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/TRowbotham/URL-Parser/tests.yml?branch=master&style=flat-square)](https://github.com/TRowbotham/URL-Parser/actions)
[![Codecov](https://img.shields.io/codecov/c/github/TRowbotham/URL-Parser/master?logo=Codecov&style=flat-square&token=WDWFg8wmjW)](https://codecov.io/gh/TRowbotham/URL-Parser)
[![Packagist](https://img.shields.io/packagist/v/rowbot/url.svg?style=flat-square)](https://packagist.org/packages/rowbot/url)
[![Packagist](https://img.shields.io/packagist/dt/rowbot/url.svg?style=flat-square)](https://packagist.org/packages/rowbot/url)
A [WHATWG URL](https://url.spec.whatwg.org/) spec compliant URL parser for working with URLs and their query strings.
This API offers 2 objects that you can use to help you work with URLs; [URL](#url) and [URLSearchParams](#urlsearchparams).
## Demo
Checkout an interactive demo [here](https://url-demo.trowbotham.com/).
## Requirements
- PHP >= 8.1
- `ext-mbstring`
- `brick/math`
- `rowbot/idna`
## Installation
```bash
composer require rowbot/url
```
## URL
The URL object is the primary object for working with a URL.
### The URL constructor
`URL(string|\Stringable $url[, null|string|\Stringable $base = null, array $options = []])`
The `$options` argument accepts an array with a key `logger` whose value is an object implementing
`\VendorPrefix\Psr\Log\LoggerInterface`. See [Logging](#logging) for more information.
#### URL constructor throws
- `\VendorPrefix\Rowbot\URL\Exception\TypeError`
- When the URL parser determines that the given input is not a valid URL.
```php
use VendorPrefix\Rowbot\URL\URL;
// Construct a new URL object.
$url = new URL('https://example.com/');
// Construct a new URL object using a relative URL, by also providing the constructor with the base URL.
$url = new URL('path/to/file.php?query=string', 'http://example.com');
echo $url->href; // Outputs: "http://example.com/path/to/file.php?query=string"
// You can also pass an existing URL object to either the $url or $base arguments.
$url = new URL('https://example.org:123');
$url1 = new URL('foo/bar/', $url);
echo $url1->href; // Outputs: "https://example.org:123/foo/bar/"
// Catch the error when URL parsing fails.
try {
$url = new URL('http://2001::1]');
} catch (\VendorPrefix\Rowbot\URL\Exception\TypeError $e) {
echo 'Invalid URL';
}
```
### URL Members
Note: As a convience, both the `__get()` and `__set()` methods will throw an `\InvalidArgumentException` if you try to get or set an invalid property.
#### `string URL::href`
The `href` getter returns the serialization of the URL. The `href` setter will parse the entire string
updating all the components of the URL with the new values. Providing an invalid URL will cause the
setter to throw a `\VendorPrefix\Rowbot\URL\TypeError`.
#### `readonly string URL::origin`
The `origin` member is readonly. Its output is in the form of `scheme://host:port`. If a URL does not
have a port, then that will be excluded from the output.
#### `string URL::protocol`
The `protocol` getter, also known as a scheme, returns the protocol of the URL, such as http, ftp, or ssh.
The `protocol` setter is used to change the URLs protocol.
#### `string URL::username`
The `username` getter returns the username portion of the URL, or an empty string if the URL does not contain a username. The `username` setter changes the URLs username.
#### `string URL::password`
The `password` getter returns the password portion of the URL, or an empty string if the URL does not contain a password. The `password` setter changes the URLs password.
#### `string URL::host`
The `host` getter returns the combination of `hostname` and `port`. The output would look like `hostname:port`. If the URL does not have a port, then the port is not present in the output. The `host` setter allows you to change both the `hostname` and `port` at the same time.
#### `string URL::hostname`
The `hostname` getter returns the hostname of the URL. For example, the hostname of `https://example.com:31` would be `example.com`. The `hostname` setter will change the hostname portion of the URL.
#### `string URL::port`
The `port` getter returns an integer as a string representing the URLs port. If the URL does not have a port, the empty string will be returned instead. The `port` setter updates the URLs port.
#### `string URL::pathname`
The `pathname` getter returns the URLs path. The `pathname` setter updates the URLs path.
#### `string URL::search`
The `search` getter returns the URLs query string. The `search` setter updates the URLs URLSearchParams list.
#### `readonly URLSearchParams URL::searchParams`
Returns the URLSearchParams object associated with this URL allowing you to modify the query parameters without having to clobber the entire query string. This will always return the same object.
#### `string URL::hash`
The `hash` getter, also known as a URLs fragment, returns the portion of the URL that follows the "#" character. The `hash` setter updates the portion of the URL that follows the "#".
#### `bool URL::canParse(string|\Stringable $url[, null|string|\Stringable $base = null])`
A static method that allows the user to quickly check if a URL is parsable, without needing to construct a new URL object and wrapping it with a try/catch statement.
#### `string URL::toJSON()`
Returns a JSON encoded string of the URL. Note that this method escapes forward slashes, which is not the default for PHPs `json_encode()`, but matches the default behavior of JavaScripts `JSON.stringify()`. If you wish to control the serialization, then pass the URL obect to the `json_encode()` function.
#### `string URL::jsonSerialize()`
The URL object implements the `JsonSerializable` interface allowing you to pass the object as a whole to the json_encode() function.
#### `string URL::toString()`
Returns the serialization of the URL.
#### `string URL::__toString()`
See [URL::toString()](#string-urltostring)
## URLSearchParams
The URLSearchParams object allows you to work with query strings when you don't need a full URL. The URLSearchParams object implements the `Iterator` interface so that you may iterate over the list of search parameters. The iterator will return an array containing exactly 2 items. The first item is the parameter name and the second item is the parameter value.
### The URLSearchParams constructor
`URLSearchParams([iterable<int|string, array<int|string, scalar|\Stringable>|(\Traversable<int|string, scalar|\Stringable>&\Countable)>|object|string|\Stringable $init])`
#### URLSearchParams constructor throws
- `\VendorPrefix\Rowbot\URL\Exception\TypeError`
- When an iterable is passed and one if its values is not iterable.
- When an iterable is passed and one of its values is not countable, such as an object that implements `\Iterator`, but not `\Countable`.
- When an iterable is passed and one of its sequences does not contain exactly 2 items, such as an array that contains only 1 string.
```php
use VendorPrefix\Rowbot\URL\URLSearchParams;
// Construct an empty list of search params.
$params = new URLSearchParams();
// Construct a new list from a query string. Remember that a leading "?" will be stripped.
$params = new URLSearchParams('?foo=bar');
// Construct a new list using an array of arrays containing strings. Alternatively, you could pass an
// object that implements the Traversable interface and whose iterator returns an array of arrays,
// with each array containing exactly 2 items.
$params = new URLSearchParams([
['foo', 'bar'],
['foo', 'bar'] // Duplicates are allowed!
['one', 'two']
]);
// Iterate over a URLSearchParams object.
foreach ($params as $index => $param) {
if ($index > 0) {
echo '&';
}
echo $param[0] . '=' . $param[1];
}
// Above loop prints "foo=bar&foo=bar&one=two".
// Construct a new list using an object
$obj = new \stdClass();
$obj->foo = 'bar';
$params = new URLSearchParams($obj);
// Copy an existing URLSearchParams object into a new one.
$params1 = new URLSearchParams($params);
```
### URLSearchParams Members
#### `void URLSearchParams::append(string $name, string $value)`
Appends a new name-value pair to the list.
#### `void URLSearchParams::delete(string $name[, string $value])`
Deletes all name-value pairs whose name is `$name` from the list. If the optional `$value` is provided,
then only pairs with the same name and value are removed.
#### `string|null URLSearchParams::get(string $name)`
Returns the value of the first name-value pair whose name is `$name` in the list or null if there are no name-value pairs whose name is `$name` in the list.
#### `string[] URLSearchParams::getAll(string $name)`
Returns a list of values of all name-value pairs whose name is `$name`, in list order, or the empty list if there are no name-value pairs whose name is `$name` in the list.
#### `bool URLSearchParams::has(string $name[, string $value])`
Returns true if there is a name-value pair in the list, and false otherwise.
#### `void URLSearchParams::set(string $name, string $value)`
If the list contains name-value pairs whose name is `$name`, the first name-value pair in the list whose name is `$name` will have its value changed to `$value` and all others following it in the list will be removed. If the list does not contain a name-value pair whose name is `$name` then the new name-value pair will be appended to the list.
#### `void URLSearchParams::sort()`
Sorts the list of search params by comparing code units. The relative order of name-value pairs with the same name are preserved.
#### `string URLSearchParams::toString()`
Returns the serialization of the list of name-value pairs.
### `int URLSearchParams::$size`
Returns the number of query parameters in the list.
#### `string URLSearchParams::__toString()`
See [URLSearchParams::toString()](#string-urlsearchparamstostring)
## Logging
The given logger logs validation errors. Entries with a level of `warning` are fatal errors that cause the parser to
fail. Entries with a level of `notice` are not fatal. All validation errors have an `input` key and either a `column`
or `column_range` offset key. Column offsets start at 1.
### Logging context
| Key | Type | Description |
| ---------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `input` | `string` | The input string that the parser is operating on at the time of error. |
| `column` | `positive-int` | The column offset of the error. |
| `column_range` | `array{0: positive-int, 1: positive-int}` | Index 0 is the starting column offset, and index 1 is the end column offset. The range is inclusive. |
| `idn_errors` | `list<string>` | A list of strings that represent IDN error constant names. |
| `unicode_domain` | `string` | The domain name as a Unicode string. |
@@ -0,0 +1,60 @@
{
"name": "rowbot/url",
"description": "A WHATWG URL spec compliant URL parser for working with URLs and their query strings.",
"keywords": [
"url",
"url-parser",
"uri",
"querystring",
"query-string",
"url-parsing",
"whatwg"
],
"license": "MIT",
"authors": [
{
"name": "Trevor Rowbotham",
"homepage": "https://trowbotham.com",
"role": "Developer"
}
],
"require": {
"php": ">=8.1",
"ext-mbstring": "*",
"brick/math": "^0.8.13 || ^0.9",
"psr/log": "^3.0",
"rowbot/idna": "^0.1.5"
},
"require-dev": {
"guzzlehttp/guzzle": "^7.0",
"phpstan/phpstan": "^1.9",
"phpstan/phpstan-deprecation-rules": "^1.0",
"phpstan/phpstan-strict-rules": "^1.0",
"phpunit/phpunit": "^10.0 || ^11.0",
"slevomat/coding-standard": "^8.0",
"squizlabs/php_codesniffer": "^3.7.1",
"symfony/cache": "^5.0 || ^6.0"
},
"autoload": {
"psr-4": {
"VendorPrefix\\Rowbot\\URL\\": "src/"
}
},
"autoload-dev": {
"psr-4": {
"VendorPrefix\\Rowbot\\URL\\Tests\\": "tests/"
}
},
"scripts": {
"phpunit": "phpunit --coverage-text",
"test": [
"@phpunit"
]
},
"config": {
"sort-packages": true,
"allow-plugins": {
"dealerdirect/phpcodesniffer-composer-installer": true
}
}
}
@@ -0,0 +1,23 @@
includes:
- vendor/phpstan/phpstan-strict-rules/rules.neon
- vendor/phpstan/phpstan-deprecation-rules/rules.neon
parameters:
level: max
treatPhpDocTypesAsCertain: false
paths:
- src
ignoreErrors:
-
message: '#Call to function is_object\(\) with object will always evaluate to true\.#'
path: src/URLSearchParams.php
count: 1
-
message: '#Cannot use array destructuring on Countable&iterable<int\|string, bool\|float\|int\|string\|Stringable>\.#'
path: src/URLSearchParams.php
count: 1
# Note to self: You can't escape single quotes in neon. Another possible alternative would be to replace single quotes with \x27.
@@ -0,0 +1,19 @@
<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
backupGlobals="false"
backupStaticProperties="false"
bootstrap="vendor/autoload.php"
cacheDirectory=".phpunit.cache"
colors="true"
xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.5/phpunit.xsd">
<source>
<include>
<directory suffix=".php">./src</directory>
</include>
</source>
<testsuites>
<testsuite name="Full Test Suite">
<directory>./tests</directory>
</testsuite>
</testsuites>
</phpunit>
@@ -0,0 +1,11 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Rowbot\URL;
class APIParserErrorType {
public const NONE = 'none';
public const URL = 'url';
public const BASE = 'base';
}
@@ -0,0 +1,27 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Rowbot\URL;
final class APIParserResult {
/**
* @readonly
* @var URLRecord|null
*/
public $url;
/**
* @readonly
* @var APIParserErrorType
*/
public $error;
/**
* @param APIParserErrorType::* $error
*/
public function __construct( ?URLRecord $urlRecord, $error ) {
$this->url = $urlRecord;
$this->error = $error;
}
}
@@ -0,0 +1,139 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Rowbot\URL;
use VendorPrefix\Psr\Log\LoggerAwareInterface;
use VendorPrefix\Psr\Log\LoggerAwareTrait;
use VendorPrefix\Psr\Log\LoggerInterface;
use VendorPrefix\Rowbot\URL\State\StatusCode;
use VendorPrefix\Rowbot\URL\String\StringBuffer;
use VendorPrefix\Rowbot\URL\String\USVStringInterface;
use function mb_strlen;
use function strlen;
use function substr;
use const PREG_OFFSET_CAPTURE;
class BasicURLParser implements LoggerAwareInterface {
use LoggerAwareTrait;
public function __construct( ?LoggerInterface $logger = null ) {
$this->logger = $logger;
}
/**
* The parser can parse both absolute and relative URLs. If a relative URL is given, a base URL must also be given
* so that an absolute URL can be resolved. It can also parse individual parts of a URL when the default starting
* state is overridden, however, a previously parsed URL record object must be provided in this case.
*
* @see https://url.spec.whatwg.org/#concept-basic-url-parser
*
* @param USVStringInterface $input A UTF-8 encoded string consisting of only scalar
* values, excluding surrogates.
* @param URLRecord|null $base (optional) This represents the base URL, which in
* most cases, is the document's URL, it may also be
* a node's base URI or whatever base URL you wish to
* resolve relative URLs against. Default is null.
* @param string|null $encodingOverride (optional) Overrides the default ouput encoding,
* which is UTF-8. This option exists solely for the
* use of the HTML specification and should never be
* changed.
* @param URLRecord|null $url (optional) This represents an existing URL record
* object that should be modified based on the input
* URL and optional base URL. Default is null.
* @param ParserState|null $stateOverride (optional) An object implementing the
* \VendorPrefix\Rowbot\URL\ParserState interface that overrides
* the default start state, which is the Scheme Start
* State. Default is null.
*
* @return URLRecord|false
*
* @param ?ParserState::* $stateOverride
*/
public function parse(
USVStringInterface $input,
?URLRecord $base = null,
?string $encodingOverride = null,
?URLRecord $url = null,
?string $stateOverride = null
) {
$count = 0;
if ( $url === null ) {
$url = new URLRecord();
$originalInput = $input;
$input = $input->replaceRegex( '/^[\x00-\x20]+|[\x00-\x20]+$/u', '', - 1, $count );
if ( $count !== 0 ) {
// Validation error.
( $nullsafeVariable1 = $this->logger ) ? $nullsafeVariable1->notice( 'invalid-URL-unit', [
'input' => (string) $originalInput,
'column_range' => ( static function () use ( $originalInput ): array {
$originalInput->matches( '/^[\x00-\x20]+|[\x00-\x20]+$/u', $matches, PREG_OFFSET_CAPTURE );
if ( $matches[0][1] === 0 ) {
return [ 1, strlen( $matches[0][0] ) ];
}
return [ $originalInput->length() - strlen( $matches[0][0] ) + 1, $originalInput->length() ];
} )(),
] ) : null;
}
}
$originalInput = $input;
$input = $input->replaceRegex( '/[\x09\x0A\x0D]+/u', '', - 1, $count );
if ( $count !== 0 ) {
// Validation error.
( $nullsafeVariable2 = $this->logger ) ? $nullsafeVariable2->notice( 'invalid-URL-unit', [
'input' => (string) $originalInput,
'column_range' => ( static function () use ( $originalInput ): array {
$originalInput->matches( '/[\x09\x0A\x0D]+/u', $matches, PREG_OFFSET_CAPTURE );
$start = mb_strlen( substr( (string) $originalInput, 0, $matches[0][1] ), 'utf-8' );
return [ $start + 1, $start + strlen( $matches[0][0] ) ];
} )(),
] ) : null;
}
$iter = $input->getIterator();
$iter->rewind();
// length + imaginary eof character
$length = $input->length() + 1;
$buffer = new StringBuffer();
$context = new ParserContext(
$input,
$iter,
$buffer,
$url,
$base,
$stateOverride,
$encodingOverride,
$this->logger
);
do {
$handler = ParserState::createHandlerFor( $context->state );
$status = $handler->handle( $context, $iter->current() );
if ( $status === StatusCode::CONTINUE ) {
$status = StatusCode::OK;
continue;
}
$iter->next();
} while ( $status === StatusCode::OK && $iter->key() < $length );
switch ( $status ) {
case StatusCode::FAILURE:
return false;
default:
return $url;
}
}
}
@@ -0,0 +1,66 @@
<?php
declare( strict_types=1 );
namespace VendorPrefix\Rowbot\URL\Component;
use VendorPrefix\Rowbot\URL\String\Exception\UndefinedIndexException;
use VendorPrefix\Rowbot\URL\URLRecord;
use function count;
abstract class AbstractPath implements PathInterface {
/**
* @var list<PathSegment>
*/
protected $list;
/**
* @param list<PathSegment> $paths
*/
public function __construct( array $paths = [] ) {
$this->list = $paths;
}
public function count(): int {
return count( $this->list );
}
public function first(): PathSegment {
if ( ! isset( $this->list[0] ) ) {
throw new UndefinedIndexException();
}
return $this->list[0];
}
public function isEmpty(): bool {
return $this->list === [];
}
public function potentiallyStripTrailingSpaces( URLRecord $url ): void {
if ( ! $this->isOpaque() ) {
return;
}
if ( $url->fragment !== null ) {
return;
}
if ( $url->query !== null ) {
return;
}
$this->list[0]->stripTrailingSpaces();
}
public function __clone() {
$list = [];
foreach ( $this->list as $path ) {
$list[] = clone $path;
}
$this->list = $list;
}
}

Some files were not shown because too many files have changed in this diff Show More