I like that you separate out the required options from the optional ones. If you don't use a Builder, then for optional parameters, even when there are no required parameters, I'd definitely use an associative array or "map". I think you are calling this just an "array" because PHP calls it that, but I'm not sure.
Builder Pattern lets you build the most airtight API, as @maple_shaft said. It prevents clients from entering invalid keys into the parameter array and its functional nature lets you fail fast as soon as an invalid value is passed. I would agree that that would be the best answer in most cases.
But the Builder pattern can require a fair amount of up-front programming work to make your API easy to use for your clients. It may not be as PHP-ish as your associative arrays - I wouldn't know. For completeness I feel I should mention some other options. The first one may be what you are doing already...
Named Parameter Map
class MyApi {
const Param1Name = 0;
const Param2Name = 1;
// etc.
public function sampleApiMethod($myParamHash) {
//Method Code
$localParam1 = $myParamHash[Param1Name]
}
}
// Load up params using pre-defined symbolic names to prevent typos
$myParamHash = array (MyApi::Param1Name => 5,
MyApi::Param2Name => 9);
// call method
sampleApiMethod($myParamHash);
The beauty of this option (or the builder) is that it makes it clear which parameter is which, thus avoiding a lot of potential errors.
Default Values
I just did a quick search, and it seems that PHP supports default values for arguments. These are probably better than Telescoping Methods, but there may be some cases where telescoping works and default values don't so I'll mention...
Telescoping Methods
Not sure if this works in php, but Something like:
public function sampleApiMethod($reqVal1, $reqVal2, $additionalOptions) {
//Method Code
}
public function sampleApiMethod($reqVal1, $reqVal2) {
sampleApiMethod($reqVal1, $reqVal2, null);
}
public function sampleApiMethod($reqVal1) {
sampleApiMethod($reqVal1, null, null);
}
I'm using "null" for default values. But for an API, this makes things much easier on the caller without the work of creating a builder. Just put the most commonly used arguments first and provide sensible defaults in your telescoping methods.
Re-Examine Your Model
Almost all useful programs model some real-world things or actions. An API that takes 30 parameters strikes me as a red flag that there may be some higher-level design issues in your API. You might want to provide a model for some of the things you are passing in as primitive values. Functional people would model things in terms of functions, OO people in terms of objects. Take your pick.