<?php
if ( ! defined( 'ABSPATH' ) ) exit;

/**
 * IPP Hooks & Filters Registry.
 *
 * Documents every hook available in the Palace Properties plugin and
 * provides helper methods for firing them consistently.
 *
 * Developers: use add_action() / add_filter() with these hook names.
 *
 * @package Integrate_Palace_Properties
 * @since   2.0.0
 */
class IPP_Hooks {

    /**
     * Initialize the hooks system.
     */
    public static function init() {
        // Register filter integration points that wrap existing behaviour
        add_filter( 'the_title', [ __CLASS__, 'filter_property_title' ], 20, 2 );
    }

    /* ═══════════════════════════════════════════════════════════════
     *  LIFECYCLE HOOKS — called from the webhook handler
     * ═══════════════════════════════════════════════════════════════ */

    /**
     * Fire before a property is saved/updated via webhook.
     *
     * @param int   $post_id
     * @param array $property_data Raw webhook payload.
     */
    public static function before_property_save( $post_id, $property_data ) {
        do_action( 'ipp_before_property_save', $post_id, $property_data );
    }

    /**
     * Fire after a property is saved/updated via webhook.
     *
     * @param int   $post_id
     * @param array $property_data Raw webhook payload.
     */
    public static function after_property_save( $post_id, $property_data ) {
        do_action( 'ipp_after_property_save', $post_id, $property_data );
    }

    /**
     * Fire before a property is deleted via webhook.
     *
     * @param int    $post_id
     * @param string $property_code
     */
    public static function before_property_delete( $post_id, $property_code ) {
        do_action( 'ipp_before_property_delete', $post_id, $property_code );
    }

    /**
     * Fire after a property is deleted via webhook.
     *
     * @param int    $post_id
     * @param string $property_code
     */
    public static function after_property_delete( $post_id, $property_code ) {
        do_action( 'ipp_after_property_delete', $post_id, $property_code );
    }

    /**
     * Fire when a sync cycle starts.
     *
     * @param string $subscription_id
     */
    public static function sync_started( $subscription_id ) {
        do_action( 'ipp_sync_started', $subscription_id );
    }

    /**
     * Fire when a sync cycle completes.
     *
     * @param string $subscription_id
     * @param int    $count Number of properties synced.
     */
    public static function sync_completed( $subscription_id, $count ) {
        do_action( 'ipp_sync_completed', $subscription_id, $count );
    }

    /**
     * Fire after gallery images are synced for a property.
     *
     * @param int   $post_id
     * @param array $image_ids
     */
    public static function gallery_updated( $post_id, $image_ids ) {
        do_action( 'ipp_gallery_updated', $post_id, $image_ids );
    }

    /* ═══════════════════════════════════════════════════════════════
     *  RENDERING HOOKS — called from template wrappers
     * ═══════════════════════════════════════════════════════════════ */

    /**
     * Fire before the archive page renders.
     *
     * @param string $template_slug
     */
    public static function before_archive( $template_slug ) {
        do_action( 'ipp_before_archive', $template_slug );
    }

    /**
     * Fire after the archive page renders.
     *
     * @param string $template_slug
     */
    public static function after_archive( $template_slug ) {
        do_action( 'ipp_after_archive', $template_slug );
    }

    /**
     * Fire before a single property page renders.
     *
     * @param int                $post_id
     * @param IPP_Property_Helper $prop
     */
    public static function before_single( $post_id, $prop ) {
        do_action( 'ipp_before_single', $post_id, $prop );
    }

    /**
     * Fire after a single property page renders.
     *
     * @param int                $post_id
     * @param IPP_Property_Helper $prop
     */
    public static function after_single( $post_id, $prop ) {
        do_action( 'ipp_after_single', $post_id, $prop );
    }

    /**
     * Fire before each property card in the archive loop.
     *
     * @param int                $post_id
     * @param IPP_Property_Helper $prop
     */
    public static function before_card( $post_id, $prop ) {
        do_action( 'ipp_before_card', $post_id, $prop );
    }

    /**
     * Fire after each property card in the archive loop.
     *
     * @param int                $post_id
     * @param IPP_Property_Helper $prop
     */
    public static function after_card( $post_id, $prop ) {
        do_action( 'ipp_after_card', $post_id, $prop );
    }

    /**
     * Fire before gallery renders.
     *
     * @param int   $post_id
     * @param array $images
     */
    public static function before_gallery( $post_id, $images ) {
        do_action( 'ipp_before_gallery', $post_id, $images );
    }

    /**
     * Fire after gallery renders.
     *
     * @param int   $post_id
     * @param array $images
     */
    public static function after_gallery( $post_id, $images ) {
        do_action( 'ipp_after_gallery', $post_id, $images );
    }

    /**
     * Fire before agent card renders.
     *
     * @param int                $post_id
     * @param IPP_Property_Helper $prop
     */
    public static function before_agent_card( $post_id, $prop ) {
        do_action( 'ipp_before_agent_card', $post_id, $prop );
    }

    /**
     * Fire after agent card renders.
     *
     * @param int                $post_id
     * @param IPP_Property_Helper $prop
     */
    public static function after_agent_card( $post_id, $prop ) {
        do_action( 'ipp_after_agent_card', $post_id, $prop );
    }

    /**
     * Fire before search bar renders.
     */
    public static function before_search_bar() {
        do_action( 'ipp_before_search_bar' );
    }

    /**
     * Fire after search bar renders.
     */
    public static function after_search_bar() {
        do_action( 'ipp_after_search_bar' );
    }

    /* ═══════════════════════════════════════════════════════════════
     *  DATA FILTERS — applied automatically
     * ═══════════════════════════════════════════════════════════════ */

    /**
     * Filter property titles on palace-properties posts.
     *
     * @param string $title
     * @param int    $post_id
     * @return string
     */
    public static function filter_property_title( $title, $post_id = 0 ) {
        if ( ! $post_id ) return $title;
        $post = get_post( $post_id );
        if ( ! $post || $post->post_type !== 'palace-properties' ) return $title;
        return apply_filters( 'ipp_property_title', $title, $post_id );
    }

    /* ═══════════════════════════════════════════════════════════════
     *  HOOK REGISTRY — returns list of all hooks for documentation
     * ═══════════════════════════════════════════════════════════════ */

    /**
     * Get all registered hooks and their descriptions.
     *
     * @return array [ 'actions' => [...], 'filters' => [...] ]
     */
    public static function get_registry() {
        return [
            'actions' => [
                // Lifecycle
                'ipp_before_property_save'   => 'Fires before a property is saved via webhook. Args: $post_id, $property_data',
                'ipp_after_property_save'    => 'Fires after a property is saved via webhook. Args: $post_id, $property_data',
                'ipp_before_property_delete'  => 'Fires before a property is deleted. Args: $post_id, $property_code',
                'ipp_after_property_delete'   => 'Fires after a property is deleted. Args: $post_id, $property_code',
                'ipp_sync_started'           => 'Fires when a sync cycle begins. Args: $subscription_id',
                'ipp_sync_completed'         => 'Fires when a sync cycle ends. Args: $subscription_id, $count',
                'ipp_gallery_updated'        => 'Fires after gallery images are synced. Args: $post_id, $image_ids',
                'ipp_property_synced'        => 'Fires after a property is fully synced (existing). Args: $post_id, $property_data',

                // Rendering
                'ipp_before_archive'         => 'Fires before the archive page renders. Args: $template_slug',
                'ipp_after_archive'          => 'Fires after the archive page renders. Args: $template_slug',
                'ipp_before_single'          => 'Fires before a single property page renders. Args: $post_id, $prop',
                'ipp_after_single'           => 'Fires after a single property page renders. Args: $post_id, $prop',
                'ipp_before_card'            => 'Fires before each property card. Args: $post_id, $prop',
                'ipp_after_card'             => 'Fires after each property card. Args: $post_id, $prop',
                'ipp_before_gallery'         => 'Fires before gallery renders. Args: $post_id, $images',
                'ipp_after_gallery'          => 'Fires after gallery renders. Args: $post_id, $images',
                'ipp_before_agent_card'      => 'Fires before agent card renders. Args: $post_id, $prop',
                'ipp_after_agent_card'       => 'Fires after agent card renders. Args: $post_id, $prop',
                'ipp_before_search_bar'      => 'Fires before search bar renders.',
                'ipp_after_search_bar'       => 'Fires after search bar renders.',
            ],
            'filters' => [
                // Data
                'ipp_property_data'          => 'Filter property data array before display. Args: $data, $post_id',
                'ipp_property_title'         => 'Filter property title. Args: $title, $post_id',
                'ipp_property_rent'          => 'Filter formatted rent. Args: $formatted, $raw, $period, $post_id',
                'ipp_property_address'       => 'Filter property address. Args: $address, $post_id',
                'ipp_property_date_available' => 'Filter formatted date available. Args: $formatted, $raw, $post_id',
                'ipp_gallery_images'         => 'Filter gallery images array. Args: $images, $post_id',
                'ipp_property_schema'        => 'Filter schema.org JSON-LD. Args: $schema, $post_id',
                'ipp_card_classes'           => 'Filter card CSS classes. Args: $classes, $post_id',
                'ipp_single_classes'         => 'Filter single page CSS classes. Args: $classes, $post_id',

                // Query
                'ipp_archive_query_args'     => 'Filter archive WP_Query args. Args: $args',
                'ipp_properties_per_page'    => 'Filter per-page count. Args: $per_page',
                'ipp_default_sort'           => 'Filter default sort. Args: $sort_by',

                // Template
                'ipp_template_path'          => 'Override template file path. Args: $path, $type, $slug',
                'ipp_card_template'          => 'Override card template path. Args: $path, $slug',
                'ipp_single_template'        => 'Override single template path. Args: $path, $slug',
                'ipp_search_template'        => 'Override search template path. Args: $path, $slug',

                // Display config
                'ipp_display_fields'         => 'Override display fields array. Args: $fields',
                'ipp_show_field'             => 'Override field visibility per property. Args: $show, $field_key, $post_id',
            ],
        ];
    }
}

// Self-initialize
IPP_Hooks::init();
