Skip to main content

​
Why Migrate?

  • Performance: Core evaluates faster than the legacy SDK
  • New Features: Access to Parameter Stores, CMAB (Contextual Multi-Armed Bandits), observabilityClient, and more
  • Future Support: All new features and improvements will only be available in Core
  • Maintenance: The legacy SDK is in maintenance mode and will only receive critical bug fixes

​
Installation and Setup

For PHP-core sdk you need to setup composer.json to run post-install.php file we provided 
composer require statsig/statsig-php-core

// composer.json
{
  "name": "awesome-php-project",
  ...
  "scripts": {
    ...
    "post-install-cmd": [
      "cd vendor/statsig/statsig-php-core && php post-install.php"
    ],
    "post-update-cmd": [
      "cd vendor/statsig/statsig-php-core && php post-install.php"
    ]
  }
}
Both require setting up chron job to fetch configs and flush events 
# Setup chron job / scheduled job to sync config and flush events
*/1 * * * * /usr/bin/php /var/www/example.com/bin/StatsigSyncConfig.php 1>> /dev/null 2>&1
*/1 * * * * /usr/bin/php /var/www/example.com/bin/StatsigFlushEvents.php 1>> /dev/null 2>&1

​
StatsigUser

// We introduced the user builder pattern
$user_builder = StatsigUserBuilder::withUserID('my_user');
$user_builder->withEmail("example@abc.com");
$user = $user_builder->build()
For usage of big IDLists (>1000 items id list), contact us before using it in php-core

​
API Changes

​
API Changes

​
Key Package and Class Changes

FeaturePhp Core SDKLegacy Php SDKStatus
Packagestatsig/statsig-php-corestatsig⚠️ Renamed
Importuse Statsig/Statsiguse Statsig/StatsigSame
OptionsStatsigOptionsStatsigOptions✓ Same
UserStatsigUser (With StatsigUserBuilder pattern)StatsigUserConstruction api changed
Initializestatsig->initialize()statsig->initialize()✓ Same
Check Gatestatsig->checkGate()statsig->checkGate()✓ Same
Get Configstatsig->getDynamicConfig()statsig->getConfig()⚠️ Naming change
Get Experimentstatsig->getExperiment()statsig->getExperiment()✓ Same
Get Layerstatsig->getLayer()statsig->getLayer()✓ Same
Log Eventstatsig->logEvent()statsig->logEvent()✓ Same
Shutdownstatsig->shutdown()statsig->shutdown()Same
For more details on the new API, see Php Core SDK documentation.

​
Behavioral Changes

The SDK now uses a lightweight YAML-based User-Agent parser based on a reduced version of the ua-parser regex definitions.This parser supports the following commonly used browsers:
  • Chrome
  • Firefox & Firefox Mobile
  • Safari & Mobile Safari
  • Chrome Mobile
  • Android
  • Edge & Edge Mobile
  • IE Mobile
  • Opera Mobile
If your use case requires identifying less common browsers, you should parse the User-Agent externally before sending it to Statsig.
User-Agent parsing and country lookup are now lazy-loaded by default to improve SDK initialization performance.If your application relies on these features being ready immediately after initialize(), you can opt in by setting:⚠️ Enabling these options will increase total initialization time.To disable these features entirely, set the StatsigOptions flags and .
The ID List functionality is disabled by default.To enable it, set the StatsigOptions flag .
The core SDK now fetches configuration specs from a new endpoint:
  • Old: v1/download_config_specs
  • New: v2/download_config_specs
If you are hosting your own pass-through proxy, ensure it supports and correctly routes the v2 endpoint.
  • If you are using the Statsig Forward Proxy (SFP), this endpoint migration is handled automatically.
** New DataStore cache format**
  • Old: (Except Node v6+)
    • config_spec cache key is: statsig.cache
    • IDLists statsig.id_lists
  • New
    • config_spec cache key: statsig|/v2/download_config_specs|plain_text|{SHA256HashedBase64(secretkey)}
    • IDLists: We don’t support idlist data store.

​
StatsigOptions Changes

The table below shows the mapping between legacy SDK options and Server Core SDK options: We introduced a lot more functionalities in new Server Core sdk. You can read more
Old OptionNew / Notes
environmentTierRenamed to be environment
eventQueueSizeRenamed to be event_logging_max_queue_size
dataAdapterRenamed to be specs_adapter
logging_adapterRenamed to be event_logging_adapter
We also introduced more features which you can configure your sdk, checkout PHP Core SDK doc page
1

Add the new Dependencies

  • Add the new SDK package/module and any required platform-specific dependencies for your environment.
  • Update import or require statements to reference the new SDK namespace or module.
  • For now - keep the old package in-place, it can be helpful to have both running in parallel momentarily during local testing for your upgrade. If needed (language dependent), you may want to alias the new package.
2

Update Initialization

  • Switch to the new initialization syntax. New SDK keys aren’t needed - if you choose to update them, ensure they have the same target apps.
  • If needed, use the appropriate builder or configuration pattern for setting options, and ensure you migrate the StatsigOptions you use, as some were renamed.
3

Update User Creation

  • Migrate to the new format for creating user objects.
  • If needed, use the builder pattern or updated constructor to set user properties.
4

Update Method Calls

  • Starting with a few calls, switch your config checks from the new to old SDK, replacing oldStatsig.getExperiment() with newStatsig.getExperiment()
  • As you change the package usage, conduct some testing of your service locally or with existing test patterns, to build confidence in the new SDK’s operation.
  • As you migrate additional calls, update method names if they’ve changed (notably, get_config() to get_dynamic_config)
  • Once comfortable with the operation of the new SDK from call-by-call migration, consider the use of refactoring tools to migrate the bulk of your remaining calls.
5

Test Thoroughly

  • Verify that all of your configs are successfully migrated - run your test suites end-to-end.
6

Remove old SDK

  • Remove references to the old SDK, and clean up old initialization and import logic.

​
Need Help?

If you encounter any issues during migration, please reach out to us: