Snippet: function astrpos()

I found myself trying to locate a PHP function in their library last week that didnâ€™t seem to exist. I had a number of strings in an array, and needed to simply find out if one of them was in a string â€“ and I needed to do it at various points. However, I could only find functions that let me search for a single needle in an array of haystacks.

So I made one myself:

Source Code - astrpos()

Source code: Function astrpos()

<?php
 
/**
 * function astrpos()
 *
 * Function to find the position of the first instance of any needle 
 * from an array of strings within a string
 * 
 *
 * @author      Stuart Jones <stuart@random-tweak.co.uk>
 * @copyright   Copyright 2008 Stuart Jones
 * @version    08.10.13
 * @license   <a href="http://www.gnu.org/licenses/gpl.html<br />
" title="http://www.gnu.org/licenses/gpl.html<br />
">http://www.gnu.org/licenses/gpl.html<br />
</a> * 
 * @param    string          $haystack
 * @param    array&lt;string&gt;   $needles
 * @param   [int          $offset]
 * @param   [int          $flags]
 */
 
 
// define constants for function flags 
if (!defined('ASTR_NEEDLE_ORDER')) { define('ASTR_NEEDLE_ORDER', 1); }
if (!defined('ASTR_STRING_ORDER')) { define('ASTR_STRING_ORDER', 2); }
 
 
 
 
function astrpos($haystack, $needles, $offset = 0, $flags = 0)
{
 
 // some error handling for incoming values 
 $backtrace = debug_backtrace();
 
  if (!is_string($haystack)) {
 
   trigger_error('Invalid argument 1 for ' . __FUNCTION__ . '() 
    - expecting string, called in ' . $backtrace[0]['file'] . ' 
    on line ' . $backtrace[0]['line'] . ' and defined', E_USER_WARNING);
 
    return false;
 
  }
 
  if (empty($haystack)) {
 
    trigger_error('Invalid argument 1 for ' . __FUNCTION__ . '() 
    - cannot be an empty string, called in ' . $backtrace[0]['file'] . ' 
   on line ' . $backtrace[0]['line'] . ' and defined', E_USER_WARNING);
 
    return false;
 
  }
 
 
 
  if (!is_array($needles)) {
 
   trigger_error('Invalid argument 2 for ' . __FUNCTION__ . '() 
    - expecting array, called in ' . $backtrace[0]['file'] . ' 
   on line ' . $backtrace[0]['line'] . ' and defined', E_USER_WARNING);
 
    return false;
 
  }
 
  if (empty($needles)) {
 
   trigger_error('Invalid argument 2 for ' . __FUNCTION__ . '() 
    - cannot be an empty array, called in ' . $backtrace[0]['file'] . ' 
    on line ' . $backtrace[0]['line'] . ' and defined', E_USER_WARNING);
 
    return false;
 
  }
 
 
 
  if (!is_int($offset) || $offset < 0) {
 
   trigger_error('Invalid argument 3 for ' . __FUNCTION__ . '() 
    - expecting positive integer, called in ' . $backtrace[0]['file'] . ' 
    on line ' . $backtrace[0]['line'] . ' and defined', E_USER_WARNING);
 
    return false;
 
  }
 
 
 
  if (!is_int($flags) || $flags < 0) {
 
   trigger_error('Invalid argument 3 for ' . __FUNCTION__ . '() 
    - expecting positive integer, called in ' . $backtrace[0]['file'] . ' 
    on line ' . $backtrace[0]['line'] . ' and defined', E_USER_WARNING);
 
    return false;
 
  }
 
 
 
  // the bit that does the work 
  $astrpos = false;
 
  foreach ($needles as $needle) {
   // cycle through the needles
 
   $strpos = false;
 
   if (($strpos = strpos($haystack, $needle, $offset)) !== false) {
 
     if ($flags && ASTR_NEEDLE_ORDER) {
 
       return $strpos;
 
      } 
 
 
      if (($astrpos > $strpos) || ($astrpos === false)) {
 
        $astrpos = $strpos;  
 
      }
 
    }
 
  }
 
 
 
  return $astrpos;
 
}
 
?>

Licence

The program/snippet/script provided in this post is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Documentation - astrpos()

Description

int astrpos ( string $haystack, array $needles [, $offset [, int $flags ] ] )
Returns the numeric position of either the first needle found in the haystack, or the first instance of a needle in the haystack.

Parameters

haystack
The string to search in
needle
An array of strings to search in the haystack for
offset
The optional offset parameter allows you to specify which character in haystack to start searching. The position returned is still relative to the beginning of haystack.
flags
Option settings for how the search is conducted:
- ASTR_NEEDLE_ORDER returns the first instance of a needle
- ASTR_STRING_ORDER retusn the first instance of any needle

Return Values

Returns the position as an integer. If needle is not found, astrpos() will return Boolean false.
Warning: This function may return Boolean FALSE, but may also return a non-Boolean value which evaluates to FALSE, such as 0 or "". Make sure to use the === operator for testing the return value of this function.

Examples - astrpos()

<?php
 
include_once('astrpos.php'); // or however you want to include it
 
$needles = array(
  'apple',
  'banana',
 'pear',
 'orange'
);
 
$haystack = 'The fruiterer has some bananas and apples today. Unfortunately, there are no oranges, but the pears will be in tomorrow.';
 
// this will return the position of 'banana' - the first needle in the haystack
echo astrpos($haystack, $needles) . '<br>';
 
// this will return the position of 'apple' - the first needle in the array of needles
echo astrpos($haystack, $needles, 0, ASTR_NEEDLE_ORDER) . '<br>';
 
// this will return the position of 'orange' - the first needle in the haystack after the offset of 50
echo astrpos($haystack, $needles, 50) . '<br>';
 
// this will return the position of 'pear' - the first needle in the array of needles found after the offset of 50
echo astrpos($haystack, $needles, 50, ASTR_NEEDLE_ORDER) . '<br>';
 
?>