> ## Documentation Index
> Fetch the complete documentation index at: https://statsig-4b2ff144-kill-dead-node-pages.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Php Core SDK Migration Guide

> Migrate from the legacy Php Server SDK to the new Php Core SDK

export const waitForUserAgentInit_0 = "wait_for_user_agent_init"

export const waitForCountryLookupInit_0 = "wait_for_country_lookup_init"

export const disableUserAgentParsing_0 = "disable_user_agent_parsing"

export const disableCountryLookup_0 = "disable_country_lookup"

export const enableIdLists_0 = "enable_id_lists"

export const sdkType_0 = "Php"

## Why Migrate?

* **Performance**: {sdkType_0} 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 {sdkType_0} Core
* **Maintenance**: The legacy {sdkType_0} 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

<CodeGroup>
  ```bash PHP Core theme={null}
  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"
      ]
    }
  }
  ```

  ```bash PHP Legacy theme={null}
  composer require statsig/statsigsdk
  ```
</CodeGroup>

Both require setting up chron job to fetch configs and flush events

<CodeGroup>
  ```bash PHP Core theme={null}
  # 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
  ```

  ```bash Legacy Php theme={null}
  # Create a cron job that runs as statsigsync every minute
  echo '*/1 * * * * statsigsync php /my/path/to/statsig/sync.php --secret <STATSIG_SECRET_KEY> > /dev/null' | sudo tee /etc/cron.d/statsigsync
  echo '*/1 * * * * statsigdata php /my/path/to/statsig/send.php --secret <STATSIG_SECRET_KEY> > /dev/null' | sudo tee /etc/cron.d/statsigdata
  sudo service cron reload   
  ```
</CodeGroup>

## StatsigUser

<CodeGroup>
  ```php Php Core theme={null}
  // We introduced the user builder pattern
  $user_builder = StatsigUserBuilder::withUserID('my_user');
  $user_builder->withEmail("example@abc.com");
  $user = $user_builder->build()
  ```

  ```Php Php Legacy theme={null}
  $user = StatsigUser::withUserID("my_user");
  $user = user->setEmail("example@abc.com");
  ```
</CodeGroup>

<Info>For usage of big IDLists (>1000 items id list), contact us before using it in php-core </Info>

## API Changes

## API Changes

### Key Package and Class Changes

| Feature        | Php Core SDK                                    | Legacy Php SDK             | Status                   |
| -------------- | ----------------------------------------------- | -------------------------- | ------------------------ |
| Package        | `statsig/statsig-php-core`                      | `statsig`                  | ⚠️ Renamed               |
| Import         | `use Statsig/Statsig`                           | `use Statsig/Statsig`      | Same                     |
| Options        | `StatsigOptions`                                | `StatsigOptions`           | ✓ Same                   |
| User           | `StatsigUser (With StatsigUserBuilder pattern)` | `StatsigUser`              | Construction api changed |
| Initialize     | `statsig->initialize()`                         | `statsig->initialize()`    | ✓ Same                   |
| Check Gate     | `statsig->checkGate()`                          | `statsig->checkGate()`     | ✓ Same                   |
| Get Config     | `statsig->getDynamicConfig()`                   | `statsig->getConfig()`     | ⚠️ Naming change         |
| Get Experiment | `statsig->getExperiment()`                      | `statsig->getExperiment()` | ✓ Same                   |
| Get Layer      | `statsig->getLayer()`                           | `statsig->getLayer()`      | ✓ Same                   |
| Log Event      | `statsig->logEvent()`                           | `statsig->logEvent()`      | ✓ Same                   |
| Shutdown       | `statsig->shutdown()`                           | `statsig->shutdown()`      | Same                     |

For more details on the new API, see [Php Core SDK documentation](/server-core/php-core).

## Behavioral Changes

<AccordionGroup>
  <Accordion title="User-Agent Parsing">
    The SDK now uses a lightweight YAML-based User-Agent parser based on a reduced version of the [ua-parser regex definitions](https://github.com/statsig-io/statsig-server-core/blob/00ad0e4024ca5d30f21892c8f2f23e836165a509/statsig-rust/resources/ua_parser_regex_lite.yaml#L4).

    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.
  </Accordion>

  <Accordion title="Lazy Initialization: User-Agent Parser & Country Lookup">
    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:

    * {waitForUserAgentInit_0}
    * {waitForCountryLookupInit_0}

    ⚠️ Enabling these options will increase total initialization time.

    To **disable** these features entirely, set the `StatsigOptions` flags {disableUserAgentParsing_0} and {disableCountryLookup_0}.
  </Accordion>

  <Accordion title="ID List Feature">
    The ID List functionality is **disabled by default**.

    To enable it, set the `StatsigOptions` flag {enableIdLists_0}.
  </Accordion>

  <Accordion title="Endpoint Changes (v1 to v2)">
    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.
  </Accordion>

  <Accordion title="DataStore cache format">
    \*\* 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.
  </Accordion>
</AccordionGroup>

## 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 Option        | New / Notes                                  |
| ----------------- | -------------------------------------------- |
| `environmentTier` | Renamed to be `environment`                  |
| `eventQueueSize`  | Renamed to be `event_logging_max_queue_size` |
| `dataAdapter`     | Renamed to be `specs_adapter`                |
| `logging_adapter` | Renamed to be `event_logging_adapter`        |

We also introduced more features which you can configure your sdk, checkout PHP Core SDK doc page

## Recommended Migration Path

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Test Thoroughly">
    * Verify that all of your configs are successfully migrated - run your test suites end-to-end.
  </Step>

  <Step title="Remove old SDK">
    * Remove references to the old SDK, and clean up old initialization and import logic.
  </Step>
</Steps>

## Need Help?

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

* [Statsig Slack Community](https://statsig.com/slack)
* [GitHub Issues](https://github.com/statsig-io/statsig-server-core/issues)