# `PostHog.FeatureFlags.FlagDefinitionCacheProvider`
[🔗](https://github.com/posthog/posthog-elixir/blob/v2.18.0/lib/posthog/feature_flags/flag_definition_cache_provider.ex#L1)

Optional shared cache contract for local feature flag definitions.

Configure a provider as `{module, provider_state}` using
`:flag_definition_cache_provider`. The definition loader bounds and isolates
every callback. Cached values must be maps containing `flags`,
`group_type_mapping`, and `cohorts` (string or atom keys are accepted).
Preserve the complete envelope, including `property_matching_version`, with
the definitions. Only version 2 selects explicit property matching; older
cached envelopes omitting the version use released service legacy matching.

With a project `:api_key` and local evaluation enabled, a provider can supply
definitions without a `:secret_key`. These cache-only readers read the provider
on each refresh without invoking the fetch decision or publishing definitions.
Instances with a secret key consult the fetch decision: true fetches and
publishes fresh definitions, while false reads the cache. An empty or failed
cache preserves loaded definitions; a keyed instance without definitions can
recover by fetching directly. Provider-backed instances use the same startup,
polling, and refresh lifecycle.

A minimal provider can coordinate fetching and keep the complete envelope in
an application-owned cache:

    defmodule MyApp.PostHogDefinitionCache do
      @behaviour PostHog.FeatureFlags.FlagDefinitionCacheProvider

      def should_fetch_flag_definitions(state), do: state.fetch_owner?.()
      def get_flag_definitions(state), do: state.read.()
      def on_flag_definitions_received(state, definitions), do: state.write.(definitions)
      def shutdown(_state), do: :ok
    end

    config :posthog,
      api_key: System.fetch_env!("POSTHOG_PROJECT_TOKEN"),
      flag_definition_cache_provider: {MyApp.PostHogDefinitionCache, provider_state}

# `definitions`

```elixir
@type definitions() :: map()
```

# `provider_state`

```elixir
@type provider_state() :: any()
```

# `get_flag_definitions`

```elixir
@callback get_flag_definitions(provider_state()) :: definitions() | nil
```

Reads definitions from the shared cache, or returns nil when it is empty.

# `on_flag_definitions_received`

```elixir
@callback on_flag_definitions_received(provider_state(), definitions()) :: :ok
```

Stores a complete definition envelope fetched from PostHog.

# `should_fetch_flag_definitions`

```elixir
@callback should_fetch_flag_definitions(provider_state()) :: boolean()
```

Returns whether a secret-key-backed SDK instance should fetch fresh definitions from PostHog.

# `shutdown`

```elixir
@callback shutdown(provider_state()) :: :ok
```

Releases resources owned by the provider.

---

*Consult [api-reference.md](api-reference.md) for complete listing*