Login | ViewVC Help
View File | Revision Log | Show Annotations | Download File | View Changeset | Root Listing
root/oidinfo_api/trunk/oid_utils.inc.phps
(Generate patch)

Comparing trunk/oid_utils.inc.phps (file contents):
Revision 15 by daniel-marschall, Sat Dec 19 21:28:32 2020 UTC vs.
Revision 16 by daniel-marschall, Sun May 23 21:07:22 2021 UTC

# Line 2 | Line 2
2  
3   /*
4   * OID-Utilities for PHP
5 < * Copyright 2011-2020 Daniel Marschall, ViaThinkSoft
6 < * Version 2020-09-12
5 > * Copyright 2011-2021 Daniel Marschall, ViaThinkSoft
6 > * Version 2021-05-21
7   *
8   * Licensed under the Apache License, Version 2.0 (the "License");
9   * you may not use this file except in compliance with the License.
# Line 31 | Line 31 | define('OID_DOT_REQUIRED',  2);
31   * Checks if an OID has a valid dot notation.
32   * @author  Daniel Marschall, ViaThinkSoft
33   * @version 2014-12-09
34 < * @param   $oid (string)<br />
34 > * @param   string $oid<br />
35   *              An OID in dot notation.
36 < * @param   $allow_leading_zeroes (bool)<br />
36 > * @param   boolean $allow_leading_zeroes<br />
37   *              true of leading zeroes are allowed or not.
38 < * @param   $allow_leading_dot (bool)<br />
38 > * @param   boolean $allow_leading_dot<br />
39   *              true of leading dots are allowed or not.
40 < * @return  (bool) true if the dot notation is valid.
40 > * @return  boolean true if the dot notation is valid.
41   **/
42   function oid_valid_dotnotation($oid, $allow_leading_zeroes=true, $allow_leading_dot=false, $min_len=0) {
43          $regex = oid_validation_regex($allow_leading_zeroes, $allow_leading_dot, $min_len);
# Line 50 | Line 50 | function oid_valid_dotnotation($oid, $al
50   * Returns a full regular expression to validate an OID in dot-notation
51   * @author  Daniel Marschall, ViaThinkSoft
52   * @version 2014-12-09
53 < * @param   $allow_leading_zeroes (bool)<br />
53 > * @param   boolean $allow_leading_zeroes<br />
54   *              true of leading zeroes are allowed or not.
55 < * @param   $allow_leading_dot (bool)<br />
55 > * @param   boolean $allow_leading_dot<br />
56   *              true of leading dots are allowed or not.
57 < * @return  (string) The regular expression
57 > * @return  string The regular expression
58   **/
59   function oid_validation_regex($allow_leading_zeroes=true, $allow_leading_dot=false, $min_len=0) {
60          $leading_dot_policy = $allow_leading_dot ? OID_DOT_OPTIONAL : OID_DOT_FORBIDDEN;
# Line 69 | Line 69 | function oid_validation_regex($allow_lea
69   * It can be inserted into regular expressions.
70   * @author  Daniel Marschall, ViaThinkSoft
71   * @version 2014-12-09
72 < * @param   $min_len (int)<br />
72 > * @param   int $min_len<br />
73   *              0="." and greater will be recognized, but not ""<br />
74   *              1=".2" and greater will be recognized<br />
75   *              2=".2.999" and greater will be recognized (default)<br />
76   *              etc.
77 < * @param   $allow_leading_zeroes (bool)<br />
77 > * @param   boolean $allow_leading_zeroes<br />
78   *              true:  ".2.0999" will be recognized<br />
79   *              false: ".2.0999" won't be recognized (default)
80 < * @param   $leading_dot_policy (int)<br />
80 > * @param   int $leading_dot_policy<br />
81   *              0 (OID_DOT_FORBIDDEN): forbidden<br />
82   *              1 (OID_DOT_OPTIONAL) : optional (default)<br />
83   *              2 (OID_DOT_REQUIRED) : enforced
84 < * @return  (string) A regular expression which matches OIDs in dot notation
84 > * @return  string|false A regular expression which matches OIDs in dot notation
85   **/
86   function oid_part_regex($min_len=2, $allow_leading_zeroes=false, $leading_dot_policy=OID_DOT_OPTIONAL) {
87          switch ($leading_dot_policy) {
# Line 96 | Line 96 | function oid_part_regex($min_len=2, $all
96                          break;
97                  default:
98                          assert(false);
99 <                        break;
99 >                        return false;
100          }
101  
102          $lead_zero            = $allow_leading_zeroes ? '0*' : '';
# Line 133 | Line 133 | function oid_part_regex($min_len=2, $all
133   * Searches all OIDs in $text and outputs them as array.
134   * @author  Daniel Marschall, ViaThinkSoft
135   * @version 2014-12-09
136 < * @param   $text (string)<br />
136 > * @param   string $text<br />
137   *              The text to be parsed
138 < * @param   $min_len (int)<br />
138 > * @param   int $min_len<br />
139   *              0="." and greater will be recognized, but not ""<br />
140   *              1=".2" and greater will be recognized<br />
141   *              2=".2.999" and greater will be recognized (default)<br />
142   *              etc.
143 < * @param   $allow_leading_zeroes (bool)<br />
143 > * @param   boolean $allow_leading_zeroes<br />
144   *              true:  ".2.0999" will be recognized<br />
145   *              false: ".2.0999" won't be recognized (default)
146 < * @param   $leading_dot_policy (int)<br />
146 > * @param   int $leading_dot_policy<br />
147   *              0 (OID_DOT_FORBIDDEN): forbidden<br />
148   *              1 (OID_DOT_OPTIONAL) : optional (default)<br />
149   *              2 (OID_DOT_REQUIRED) : enforced
150 < * @param   $requires_whitespace_delimiters (bool)<br />
150 > * @param   boolean $requires_whitespace_delimiters<br />
151   *              true:  "2.999" will be recognized, as well as " 2.999 " (default)<br />
152   *              false: "2.999!" will be reconigzed, as well as "2.999.c" (this might be used in in documentations with templates)
153 < * @return  (array<string>) An array of OIDs in dot notation
153 > * @return  string[] An array of OIDs in dot notation
154   **/
155   function parse_oids($text, $min_len=2, $allow_leading_zeroes=false, $leading_dot_policy=OID_DOT_OPTIONAL, $requires_whitespace_delimiters=true) {
156          $regex = oid_detection_regex($min_len, $allow_leading_zeroes, $leading_dot_policy, $requires_whitespace_delimiters);
# Line 164 | Line 164 | function parse_oids($text, $min_len=2, $
164   * Returns a full regular expression for detecting OIDs in dot notation inside a text.
165   * @author  Daniel Marschall, ViaThinkSoft
166   * @version 2014-12-09
167 < * @param   $min_len (int)<br />
167 > * @param   int $min_len<br />
168   *              0="." and greater will be recognized, but not ""<br />
169   *              1=".2" and greater will be recognized<br />
170   *              2=".2.999" and greater will be recognized (default)<br />
171   *              etc.
172 < * @param   $allow_leading_zeroes (bool)<br />
172 > * @param   boolean $allow_leading_zeroes<br />
173   *              true:  ".2.0999" will be recognized<br />
174   *              false: ".2.0999" won't be recognized (default)
175 < * @param   $leading_dot_policy (int)<br />
175 > * @param   int $leading_dot_policy<br />
176   *              0 (OID_DOT_FORBIDDEN): forbidden<br />
177   *              1 (OID_DOT_OPTIONAL) : optional (default)<br />
178   *              2 (OID_DOT_REQUIRED) : enforced
179 < * @param   $requires_whitespace_delimiters (bool)<br />
179 > * @param   boolean $requires_whitespace_delimiters<br />
180   *              true:  "2.999" will be recognized, as well as " 2.999 " (default)<br />
181   *              false: "2.999!" will be reconigzed, as well as "2.999.c" (this might be used in in documentations with templates)
182 < * @return  (string) The regular expression
182 > * @return  string The regular expression
183   **/
184   function oid_detection_regex($min_len=2, $allow_leading_zeroes=false, $leading_dot_policy=OID_DOT_OPTIONAL, $requires_whitespace_delimiters=true) {
185          if ($requires_whitespace_delimiters) {
# Line 202 | Line 202 | function oid_detection_regex($min_len=2,
202   * Leading dots and leading zeroes are tolerated.
203   * @author  Daniel Marschall, ViaThinkSoft
204   * @version 2014-12-16
205 < * @param   $oid (string)<br />
205 > * @param   string $oid<br />
206   *              An OID in dot notation.
207 < * @return  (string) The parent OID in dot notation.
207 > * @return  string|false The parent OID in dot notation.
208   **/
209   function oid_up($oid) {
210          $oid = sanitizeOID($oid, 'auto');
# Line 221 | Line 221 | function oid_up($oid) {
221   * Outputs the depth of an OID.
222   * @author  Daniel Marschall, ViaThinkSoft
223   * @version 2014-12-09
224 < * @param   $oid (string) An OID in dot notation (with or without leading dot)
224 > * @param   string $oid An OID in dot notation (with or without leading dot)
225   * @return  (int) The depth of the OID, e.g. 2.999 and .2.999 has the length 2.
226   **/
227   function oid_len($oid) {
# Line 239 | Line 239 | function oid_depth($oid) {
239   * The OID will not be checked for validity!
240   * @author  Daniel Marschall, ViaThinkSoft
241   * @version 2014-12-17
242 < * @param   $oid (string)<br />
242 > * @param   string $oid<br />
243   *              An OID in dot notation.
244 < * @return  (array<string>) An array with all parent OIDs.
244 > * @return  string[] An array with all parent OIDs.
245   **/
246   function oid_parents($oid) {
247          $parents = array();
# Line 267 | Line 267 | assert(oid_parents('') == array());
267   * Sorts an array containing OIDs in dot notation.
268   * @author  Daniel Marschall, ViaThinkSoft
269   * @version 2014-12-09
270 < * @param   $ary (array<string>)<br />
270 > * @param   string[] $ary<br />
271   *              An array of OIDs in dot notation.<br />
272   *              This array will be changed by this method.
273 < * @param   $output_with_leading_dot (bool)<br />
273 > * @param   boolean $output_with_leading_dot<br />
274   *              true: The array will be normalized to OIDs with a leading dot.
275   *              false: The array will be normalized to OIDs without a leading dot. (default)
276   **/
# Line 280 | Line 280 | function oidSort(&$ary, $output_with_lea
280          $none = $output_with_leading_dot ? '.' : '';
281  
282          $d = array();
283 +        $oid = null;
284          foreach ($ary as &$oid) {
285                  if (($oid == '') || ($oid == '.')) {
286                          $out[] = $none;
# Line 294 | Line 295 | function oidSort(&$ary, $output_with_lea
295          unset($oid);
296          ksort($d);
297  
298 +        $data = null;
299          foreach ($d as $firstarc => &$data) {
300                  oidSort($data);
301                  foreach ($data as &$rest) {
# Line 309 | Line 311 | function oidSort(&$ary, $output_with_lea
311   * Checks if two OIDs in dot-notation are equal
312   * @author  Daniel Marschall, ViaThinkSoft
313   * @version 2020-05-27
314 < * @param   $oidA (string)<br />
314 > * @param   string $oidA<br />
315   *              First OID
316 < * @param   $oidB (string)<br />
316 > * @param   string $oidB<br />
317   *              Second OID
318 < * @return  (bool) True if the OIDs are equal
318 > * @return  boolean|null True if the OIDs are equal, null if one of the OIDs are invalid
319   **/
320   function oid_dotnotation_equal($oidA, $oidB) {
321          $oidA = sanitizeOID($oidA, false);
# Line 329 | Line 331 | function oid_dotnotation_equal($oidA, $o
331   * Removes leading zeroes from an OID in dot notation.
332   * @author  Daniel Marschall, ViaThinkSoft
333   * @version 2015-08-17
334 < * @param   $oid (string)<br />
334 > * @param   string $oid<br />
335   *              An OID in dot notation.
336 < * @param   $leading_dot (bool)<br />
336 > * @param   boolean $leading_dot<br />
337   *              true: The OID is valid, if it contains a leading dot.<br />
338   *              false (default): The OID is valid, if it does not contain a leading dot.
339   *              'auto: Allow both
340 < * @return  (mixed) The OID without leading dots, or <code>false</code> if the OID is syntactically wrong.
340 > * @return  string|false The OID without leading dots, or <code>false</code> if the OID is syntactically wrong.
341   **/
342   $oid_sanitize_cache = array();
343   function sanitizeOID($oid, $leading_dot=false) {
# Line 381 | Line 383 | function sanitizeOID($oid, $leading_dot=
383   * This function tolerates leading dots.
384   * @author  Daniel Marschall, ViaThinkSoft
385   * @version 2014-12-16
386 < * @param   $oid (string)<br />
386 > * @param   string $oid<br />
387   *              An OID in dot notation.
388 < * @return  (mixed) The top arc of the OID or empty string if it is already the root ('.')
388 > * @return  string|false The top arc of the OID or empty string if it is already the root ('.')
389   **/
390   function oid_toparc($oid) {
391          $leadingdot = substr($oid,0,1) == '.';
# Line 410 | Line 412 | function oid_toparc($oid) {
412   * This function tolerates leading dots and leading zeroes.
413   * @author  Daniel Marschall, ViaThinkSoft
414   * @version 2014-12-20
415 < * @param   $a (string)<br />
415 > * @param   string $a<br />
416   *              An OID.
417 < * @param   $b (string)<br />
417 > * @param   string $b<br />
418   *              An OID.
419 < * @return  (string) false if both OIDs do not have a child-parent or parent-child relation, e.g. oid_distance('2.999.1.2.3', '2.999.4.5') = false, or if one of the OIDs is syntactially invalid<br />
419 > * @return  int|false  false if both OIDs do not have a child-parent or parent-child relation, e.g. oid_distance('2.999.1.2.3', '2.999.4.5') = false, or if one of the OIDs is syntactially invalid<br />
420   *              >0 if $a is more specific than $b , e.g. oid_distance('2.999.1.2', '2.999') = 2<br />
421   *              <0 if $a is more common than $b , e.g. oid_distance('2.999', '2.999.1.2') = -2
422   **/
# Line 449 | Line 451 | assert(oid_distance('2.999', '2.999.1.2'
451   * Leading zeroes are tolerated.
452   * @author  Daniel Marschall, ViaThinkSoft
453   * @version 2014-12-20
454 < * @param   $oid (string)<br />
454 > * @param   string $oid<br />
455   *              An OID.
456 < * @return  (string) The OID with a leading dot or false if the OID is syntactially wrong.
456 > * @return  string|false The OID with a leading dot or false if the OID is syntactially wrong.
457   **/
458   function oid_add_leading_dot($oid) {
459          $oid = sanitizeOID($oid, 'auto');
# Line 466 | Line 468 | function oid_add_leading_dot($oid) {
468   * Leading zeroes are tolerated.
469   * @author  Daniel Marschall, ViaThinkSoft
470   * @version 2014-12-20
471 < * @param   $oid (string)<br />
471 > * @param   string $oid<br />
472   *              An OID.
473 < * @return  (string) The OID without a leading dot or false if the OID is syntactially wrong.
473 > * @return  string|false The OID without a leading dot or false if the OID is syntactially wrong.
474   **/
475   function oid_remove_leading_dot($oid) {
476          $oid = sanitizeOID($oid, 'auto');
# Line 482 | Line 484 | function oid_remove_leading_dot($oid) {
484   * Find the common ancestor of two or more OIDs
485   * @author  Daniel Marschall, ViaThinkSoft
486   * @version 2020-05-27
487 < * @param   $oids (array)<br />
487 > * @param   string[] $oids<br />
488   *              An array of multiple OIDs, e.g. 2.999.1 and 2.999.2.3.4
489 < * @return  (mixed) The common ancestor, e.g. 2.999, or false if there is no common ancestor.
489 > * @return  string|false The common ancestor, e.g. 2.999, or false if there is no common ancestor.
490   **/
491   function oid_common_ancestor(array $oids) {
492          $shared = array();
# Line 498 | Line 500 | function oid_common_ancestor(array $oids
500                  $oid = explode('.', $oid);
501          }
502  
503 <        $max_ok = count($oids[0]);
503 >        $max_ok = strlen($oids[0]);
504          for ($i=1; $i<count($oids); $i++) {
505 <                for ($j=0; $j<min(count($oids[$i]),count($oids[0])); $j++) {
505 >                for ($j=0; $j<min(strlen($oids[$i]),strlen($oids[0])); $j++) {
506                          if ($oids[$i][$j] != $oids[0][$j]) {
507                                  if ($j < $max_ok) $max_ok = $j;
508                                  break;
# Line 599 | Line 601 | function iri_arc_valid($arc, $allow_nume
601   * Checks if an IRI identifier is valid or not.
602   * @author  Daniel Marschall, ViaThinkSoft
603   * @version 2014-12-17
604 < * @param   $iri (string)<br />
604 > * @param   string $iri<br />
605   *              An OID in OID-IRI notation, e.g. /Example/test
606 < * @return  (bool) true if the IRI identifier is valid.
606 > * @return  boolean true if the IRI identifier is valid.
607   **/
608   function iri_valid($iri) {
609          if ($iri == '/') return true; // OK?
# Line 670 | Line 672 | function iri_get_long_arcs() {
672   * Tries to shorten/simplify an IRI by applying "long arcs", e.g. /2/999/123 -> /Example/123 .
673   * @author  Daniel Marschall, ViaThinkSoft
674   * @version 2020-05-22
675 < * @param   $iri (string)<br />
675 > * @param   string $iri<br />
676   *              An OID in OID-IRI notation, e.g. /Example/test
677 < * @return  (string) The modified IRI.
677 > * @return  string|false The modified IRI.
678   **/
679   function iri_add_longarcs($iri) {
680          $iri_long_arcs = iri_get_long_arcs();
# Line 712 | Line 714 | assert(iri_add_longarcs('/2/999/123') ==
714   * Checks if an ASN.1 identifier is valid.
715   * @author  Daniel Marschall, ViaThinkSoft
716   * @version 2020-05-22
717 < * @param   $id (string)<br />
717 > * @param   string $id<br />
718   *              An ASN.1 identifier, e.g. "example". Not "example(99)" or "99" and not a path like "{ 2 999 }"
719   *              Note: Use asn1_path_valid() for validating a whole ASN.1 notation path.
720 < * @return  (bool) true, if the identifier is valid: It begins with an lowercase letter and contains only 0-9, a-z, A-Z and "-"
720 > * @return  boolean true, if the identifier is valid: It begins with an lowercase letter and contains only 0-9, a-z, A-Z and "-"
721   **/
722   function oid_id_is_valid($id) {
723          // see Rec. ITU-T X.660 | ISO/IEC 9834-1, clause 7.7
# Line 731 | Line 733 | function oid_id_is_valid($id) {
733   * This function will fail (return false) if there are unresolved symbols, e.g. {iso test} is not valid while { iso 123 } is valid.
734   * @author  Daniel Marschall, ViaThinkSoft
735   * @version 2014-12-17
736 < * @param   $asn (string)<br />
736 > * @param   string $asn1<br />
737   *              An OID in ASN.1 notation.
738 < * @return  (bools) true if the identifier is valid.
738 > * @return  boolean true if the identifier is valid.
739   **/
740   function asn1_path_valid($asn1) {
741          return asn1_to_dot($asn1) != false;
# Line 803 | Line 805 | function asn1_get_standardized_array() {
805   * This function will fail (return false) if there are unresolved symbols, e.g. {iso test} will not be resolved to 1.test
806   * @author  Daniel Marschall, ViaThinkSoft
807   * @version 2014-12-17
808 < * @param   $asn (string)<br />
808 > * @param   string $asn<br />
809   *              An OID in ASN.1 notation.
810 < * @return  (string) An OID in dot notation without leading dot or false if the path is invalid.
810 > * @return  string|false An OID in dot notation without leading dot or false if the path is invalid.
811   **/
812   function asn1_to_dot($asn) {
813          $standardized = asn1_get_standardized_array();
# Line 860 | Line 862 | assert(asn1_to_dot('{  iso 3 }') == '1.3
862   * Gets the last numeric identifier of an ASN.1 notation OID.
863   * @author  Daniel Marschall, ViaThinkSoft
864   * @version 2020-06-11
865 < * @param   $asn1id (string)<br />
865 > * @param   string $asn1id<br />
866   *              An ASN.1 identifier string, e.g. { 2 example(999) test(1) }
867 < * @return  (int) The last numeric identifier arc, e.g. "1"
867 > * @return  int|false The last numeric identifier arc, e.g. "1" or false if the ID is invalid
868   **/
869   function asn1_last_identifier($asn1id) {
870          $asn1id = preg_replace('@\(\s*\d+\s*\)@', '', $asn1id);
871          $asn1id = trim(str_replace(array('{', '}', "\t"), ' ', $asn1id));
872          $ary = explode(' ', $asn1id);
873          $asn1id = $ary[count($ary)-1];
874 <        return preg_match('#[^0-9]#',$asn1id) ? $asn1id : false;
874 >        return preg_match('#[^0-9]#',$asn1id) ? (int)$asn1id : false;
875   }
876  
877   /**
# Line 877 | Line 879 | function asn1_last_identifier($asn1id) {
879   * Attention, by "soft correcting" the ID, it is not authoritative anymore, and might not be able to be resolved by ORS.
880   * @author  Daniel Marschall, ViaThinkSoft
881   * @version 2020-05-22
882 < * @param   $id (string)<br />
882 > * @param   string $id<br />
883   *              An ASN.1 identifier.
884 < * @param   $append_id_prefix (bool)<br />
884 > * @param   boolean $append_id_prefix<br />
885   *              true (default): If the identifier doesn't start with a-Z, the problem will be solved by prepending "id-" to the identifier.<br />
886   *              false: If the identifier doesn't start with a-Z, then the problem cannot be solved (method returns empty string).
887 < * @return  (string) The "soft corrected" ASN.1 identifier.<br />
887 > * @return  string The "soft corrected" ASN.1 identifier.<br />
888   *              Invalid characters will be removed.<br />
889   *              Uncorrectable start elements (0-9 or "-") will be either removed or solved by prepending "id-" (see <code>$append_id_prefix</code>)<br />
890   *              If the identifier begins with an upper case letter, the letter will be converted into lower case.

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines