Capturing events

You can send custom events using capture:

PostHog::capture(array(
  'distinctId' => 'distinct_id_of_the_user',
  'event' => 'user_signed_up'
));

Tip: We recommend using a [object] [verb] format for your event names, where [object] is the entity that the behavior relates to, and [verb] is the behavior itself. For example, project created, user signed up, or invite sent.

Setting event properties

Optionally, you can include additional information with the event by including a properties object:

PostHog::capture(array(
  'distinctId' => 'distinct_id_of_the_user',
  'event' => 'user_signed_up',
  'properties' => array(
    'login_type' => 'email',
    'is_free_trial' => 'true'
  )
));

Sending page views

If you're aiming for a backend-only implementation of PostHog and won't be capturing events from your frontend, you can send pageviews from your backend like so:

PostHog::capture(array(
  'distinctId' => 'distinct_id_of_the_user',
  'event' => '$pageview',
  'properties' => array(
    '$current_url' => 'https://example.com'
  )
));

The JavaScript Web SDK captures anonymous events by default. However, this may change depending on your person_profiles config when initializing PostHog:

1. person_profiles: 'identified_only' (recommended) (default) - Anonymous events are captured by default. PostHog only captures identified events for users where person profiles have already been created.

2. person_profiles: 'always' - Capture identified events for all events.

For example:

posthog.init('<ph_project_api_key>', {
    api_host: 'https://us.i.posthog.com',
    defaults: '2025-05-24',
    person_profiles: 'always'
})

If you've set the personProfiles config to IDENTIFIED_ONLY (the default option), anonymous events are captured by default. To capture identified events, call any of the following functions:

• identify()
• alias()
• group()
• setPersonProperties()
• setPersonPropertiesForFlags()
• setGroupPropertiesForFlags()

When you call any of these functions, it creates a person profile for the user. Once this profile is created, all subsequent events for this user will be captured as identified events.

Alternatively, you can set personProfiles to ALWAYS to capture identified events by default.