function mytheme_register_portfolio() {
    register_post_type('portfolio', array(
        'labels' => array(
            'name'          => __('Portfolio', 'mytheme'),
            'singular_name' => __('Portfolio Item', 'mytheme'),
            'add_new'       => __('Add New', 'mytheme'),
            'add_new_item'  => __('Add New Portfolio Item', 'mytheme'),
            'edit_item'     => __('Edit Portfolio Item', 'mytheme'),
            'new_item'      => __('New Portfolio Item', 'mytheme'),
            'view_item'     => __('View Portfolio Item', 'mytheme'),
            'search_items'  => __('Search Portfolio', 'mytheme'),
        ),
        'public'       => true,
        'has_archive'  => true,
        'rewrite'      => array('slug' => 'portfolio'),
        'supports'     => array('title', 'editor', 'thumbnail', 'excerpt'),
        'menu_icon'    => 'dashicons-portfolio',
        'show_in_rest' => true,
    ));
}
add_action('init', 'mytheme_register_portfolio');

Field Type: Text
Used for: Short text (names, titles)
Returns: String

Field Type: Textarea
Used for: Long text (descriptions)
Returns: String

Field Type: Number
Used for: Numeric values
Returns: Integer/Float

Field Type: Email
Used for: Email addresses
Returns: String (email)

Field Type: URL
Used for: Web addresses
Returns: String (URL)

Field Type: Image
Return Format: Array/URL/ID
Returns: Image data

Field Type: File
Return Format: Array/URL/ID
Returns: File data

Field Type: Select
Used for: Dropdown selection
Returns: Selected value(s)

Field Type: Checkbox
Used for: Multiple selections
Returns: Array of values

Field Type: Radio Button
Used for: Single selection
Returns: Selected value

Field Type: True/False
Used for: On/off toggle
Returns: Boolean (1/0)

Field Type: Relationship
Used for: Link to other posts
Returns: Array of post objects

Field Type: Repeater
Used for: Repeating field sets
Returns: Array of field groups

<?php get_header(); ?>

<div class="portfolio-single">
    <?php while (have_posts()) : the_post(); ?>

        <article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
            <header class="entry-header">
                <h1 class="entry-title"><?php the_title(); ?></h1>

                <?php
                // Get ACF fields
                $client_name = get_field('client_name');
                $project_url = get_field('project_url');
                $project_date = get_field('project_date');
                $technologies = get_field('technologies');
                ?>

                <?php if ($client_name) : ?>
                    <p class="client-name">
                        <strong>Client:</strong> <?php echo esc_html($client_name); ?>
                    </p>
                <?php endif; ?>

                <?php if ($project_date) : ?>
                    <p class="project-date">
                        <strong>Date:</strong> <?php echo esc_html(date('F Y', strtotime($project_date))); ?>
                    </p>
                <?php endif; ?>

                <?php if ($project_url) : ?>
                    <p class="project-url">
                        <a href="<?php echo esc_url($project_url); ?>" target="_blank">
                            View Live Project
                        </a>
                    </p>
                <?php endif; ?>

                <?php if ($technologies) : ?>
                    <div class="technologies">
                        <strong>Technologies:</strong>
                        <ul>
                            <?php foreach ($technologies as $tech) : ?>
                                <li><?php echo esc_html($tech); ?></li>
                            <?php endforeach; ?>
                        </ul>
                    </div>
                <?php endif; ?>
            </header>

            <div class="entry-content">
                <?php the_content(); ?>
            </div>

            <?php
            // Display gallery (ACF PRO)
            $images = get_field('project_images');
            if ($images) : ?>
                <div class="project-gallery">
                    <?php foreach ($images as $image) : ?>
                        <div class="gallery-item">
                            <a href="<?php echo esc_url($image['url']); ?>" data-lightbox="portfolio">
                                <img src="<?php echo esc_url($image['sizes']['medium']); ?>"
                                     alt="<?php echo esc_attr($image['alt']); ?>" />
                            </a>
                        </div>
                    <?php endforeach; ?>
                </div>
            <?php endif; ?>
        </article>

    <?php endwhile; ?>
</div>

<?php get_footer(); ?>

<?php get_header(); ?>

<div class="portfolio-archive">
    <header class="page-header">
        <h1>Portfolio</h1>
    </header>

    <?php if (have_posts()) : ?>
        <div class="portfolio-grid">
            <?php while (have_posts()) : the_post(); ?>

                <article id="post-<?php the_ID(); ?>" <?php post_class('portfolio-item'); ?>>
                    <?php if (has_post_thumbnail()) : ?>
                        <div class="portfolio-thumbnail">
                            <a href="<?php the_permalink(); ?>">
                                <?php the_post_thumbnail('medium'); ?>
                            </a>
                        </div>
                    <?php endif; ?>

                    <div class="portfolio-content">
                        <h2 class="entry-title">
                            <a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
                        </h2>

                        <?php
                        $client_name = get_field('client_name');
                        if ($client_name) :
                            ?>
                            <p class="client">Client: <?php echo esc_html($client_name); ?></p>
                        <?php endif; ?>

                        <div class="entry-excerpt">
                            <?php the_excerpt(); ?>
                        </div>

                        <a href="<?php the_permalink(); ?>" class="read-more">
                            View Project
                        </a>
                    </div>
                </article>

            <?php endwhile; ?>
        </div>

        <?php the_posts_pagination(); ?>

    <?php else : ?>
        <p>No portfolio items found.</p>
    <?php endif; ?>
</div>

<?php get_footer(); ?>

<?php
// Query portfolio items by client name
$args = array(
    'post_type'  => 'portfolio',
    'meta_key'   => 'client_name',
    'meta_value' => 'Acme Corporation',
);

$portfolio_query = new WP_Query($args);

if ($portfolio_query->have_posts()) :
    while ($portfolio_query->have_posts()) :
        $portfolio_query->the_post();
        the_title('<h2>', '</h2>');
    endwhile;
    wp_reset_postdata();
endif;
?>

<?php
// Get portfolio items from 2024 or later
$args = array(
    'post_type'  => 'portfolio',
    'meta_query' => array(
        array(
            'key'     => 'project_date',
            'value'   => '2024-01-01',
            'compare' => '>=',
            'type'    => 'DATE',
        ),
    ),
);

$recent_portfolio = new WP_Query($args);
?>

<?php
$args = array(
    'post_type'  => 'portfolio',
    'meta_query' => array(
        'relation' => 'AND',
        array(
            'key'     => 'client_name',
            'value'   => 'Acme',
            'compare' => 'LIKE',
        ),
        array(
            'key'     => 'project_date',
            'value'   => '2024-01-01',
            'compare' => '>=',
            'type'    => 'DATE',
        ),
    ),
);

$filtered_portfolio = new WP_Query($args);
?>

function mytheme_register_acf_fields() {
    if (function_exists('acf_add_local_field_group')) {
        acf_add_local_field_group(array(
            'key'    => 'group_portfolio',
            'title'  => 'Portfolio Fields',
            'fields' => array(
                array(
                    'key'   => 'field_client_name',
                    'label' => 'Client Name',
                    'name'  => 'client_name',
                    'type'  => 'text',
                    'required' => 1,
                ),
                array(
                    'key'   => 'field_project_url',
                    'label' => 'Project URL',
                    'name'  => 'project_url',
                    'type'  => 'url',
                ),
                array(
                    'key'   => 'field_project_date',
                    'label' => 'Project Date',
                    'name'  => 'project_date',
                    'type'  => 'date_picker',
                    'display_format' => 'd/m/Y',
                    'return_format'  => 'Y-m-d',
                ),
                array(
                    'key'   => 'field_technologies',
                    'label' => 'Technologies Used',
                    'name'  => 'technologies',
                    'type'  => 'checkbox',
                    'choices' => array(
                        'wordpress'  => 'WordPress',
                        'php'        => 'PHP',
                        'javascript' => 'JavaScript',
                        'react'      => 'React',
                    ),
                ),
            ),
            'location' => array(
                array(
                    array(
                        'param'    => 'post_type',
                        'operator' => '==',
                        'value'    => 'portfolio',
                    ),
                ),
            ),
        ));
    }
}
add_action('acf/init', 'mytheme_register_acf_fields');

<?php
if (get_field('client_name')) {
    echo 'Client: ' . esc_html(get_field('client_name'));
}
?>

<?php
// Get and echo in one function
the_field('client_name');

// Equivalent to:
echo get_field('client_name');
?>

<?php
$client = get_field('client_name', 123); // Post ID 123
?>

Return Format:
- Array: Full image data (recommended)
- URL: Image URLs only
- ID: Attachment IDs only

Library:
- all: All images in media library
- uploadedTo: Only images uploaded to this post

Min/Max:
- Min: 1 (require at least one image)
- Max: 20 (limit to 20 images)

Insert:
- append: Add new images to end
- prepend: Add new images to beginning

<?php
$images = get_field('project_gallery');

if ($images) :
    ?>
    <div class="image-gallery">
        <?php foreach ($images as $image) : ?>
            <div class="gallery-item">
                <img src="<?php echo esc_url($image['sizes']['medium']); ?>"
                     alt="<?php echo esc_attr($image['alt']); ?>"
                     title="<?php echo esc_attr($image['title']); ?>" />
            </div>
        <?php endforeach; ?>
    </div>
<?php endif; ?>

.image-gallery {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
    gap: 20px;
    padding: 20px 0;
}

.gallery-item {
    position: relative;
    overflow: hidden;
    border-radius: 8px;
}

.gallery-item img {
    width: 100%;
    height: 250px;
    object-fit: cover;
    transition: transform 0.3s ease;
}

.gallery-item:hover img {
    transform: scale(1.05);
}

<?php
$images = get_field('project_gallery');

if ($images) :
    ?>
    <div class="gallery-with-captions">
        <?php foreach ($images as $image) : ?>
            <figure class="gallery-item">
                <img src="<?php echo esc_url($image['sizes']['large']); ?>"
                     alt="<?php echo esc_attr($image['alt']); ?>" />

                <?php if ($image['caption']) : ?>
                    <figcaption>
                        <?php echo esc_html($image['caption']); ?>
                    </figcaption>
                <?php endif; ?>
            </figure>
        <?php endforeach; ?>
    </div>
<?php endif; ?>

.gallery-with-captions {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 30px;
}

.gallery-item figcaption {
    padding: 10px;
    background: #f8f9fa;
    font-size: 14px;
    color: #6c757d;
    text-align: center;
}

function mytheme_gallery_lightbox() {
    // GLightbox CSS
    wp_enqueue_style(
        'glightbox',
        'https://cdn.jsdelivr.net/npm/glightbox/dist/css/glightbox.min.css',
        array(),
        '3.2.0'
    );

    // GLightbox JS
    wp_enqueue_script(
        'glightbox',
        'https://cdn.jsdelivr.net/npm/glightbox/dist/js/glightbox.min.js',
        array(),
        '3.2.0',
        true
    );

    // Initialize lightbox
    wp_add_inline_script('glightbox', '
        document.addEventListener("DOMContentLoaded", function() {
            GLightbox({
                selector: ".glightbox"
            });
        });
    ');
}
add_action('wp_enqueue_scripts', 'mytheme_gallery_lightbox');

<?php
$images = get_field('project_gallery');

if ($images) :
    ?>
    <div class="lightbox-gallery">
        <?php foreach ($images as $image) : ?>
            <a href="<?php echo esc_url($image['url']); ?>"
               class="glightbox gallery-item"
               data-gallery="gallery1"
               data-description="<?php echo esc_attr($image['caption']); ?>">
                <img src="<?php echo esc_url($image['sizes']['medium']); ?>"
                     alt="<?php echo esc_attr($image['alt']); ?>" />
            </a>
        <?php endforeach; ?>
    </div>
<?php endif; ?>

<?php
$images = get_field('project_gallery');

if ($images) :
    ?>
    <div class="masonry-gallery">
        <?php foreach ($images as $index => $image) :
            // Vary heights for masonry effect
            $tall = ($index % 3 === 0) ? 'tall' : '';
            ?>

            <div class="gallery-item <?php echo esc_attr($tall); ?>">
                <a href="<?php echo esc_url($image['url']); ?>"
                   class="glightbox"
                   data-gallery="masonry">
                    <img src="<?php echo esc_url($image['sizes']['large']); ?>"
                         alt="<?php echo esc_attr($image['alt']); ?>" />
                </a>
            </div>

        <?php endforeach; ?>
    </div>
<?php endif; ?>

.masonry-gallery {
    column-count: 3;
    column-gap: 15px;
}

.gallery-item {
    break-inside: avoid;
    margin-bottom: 15px;
}

.gallery-item img {
    width: 100%;
    display: block;
    border-radius: 8px;
}

.gallery-item.tall {
    height: 400px;
}

@media (max-width: 768px) {
    .masonry-gallery {
        column-count: 2;
    }
}

@media (max-width: 480px) {
    .masonry-gallery {
        column-count: 1;
    }
}

<?php
$images = get_field('project_gallery');

if ($images) :
    ?>
    <div class="slider-gallery">
        <div class="slider-container">
            <?php foreach ($images as $index => $image) : ?>
                <div class="slide <?php echo ($index === 0) ? 'active' : ''; ?>"
                     data-slide="<?php echo esc_attr($index); ?>">
                    <img src="<?php echo esc_url($image['sizes']['large']); ?>"
                         alt="<?php echo esc_attr($image['alt']); ?>" />

                    <?php if ($image['caption']) : ?>
                        <div class="slide-caption">
                            <?php echo esc_html($image['caption']); ?>
                        </div>
                    <?php endif; ?>
                </div>
            <?php endforeach; ?>
        </div>

        <button class="slider-prev" aria-label="Previous image">‹</button>
        <button class="slider-next" aria-label="Next image">›</button>

        <div class="slider-dots">
            <?php foreach ($images as $index => $image) : ?>
                <button class="dot <?php echo ($index === 0) ? 'active' : ''; ?>"
                        data-slide="<?php echo esc_attr($index); ?>"
                        aria-label="Go to slide <?php echo ($index + 1); ?>"></button>
            <?php endforeach; ?>
        </div>
    </div>
<?php endif; ?>

document.addEventListener("DOMContentLoaded", function () {
    const slides = document.querySelectorAll(".slide");
    const dots = document.querySelectorAll(".dot");
    const prevBtn = document.querySelector(".slider-prev");
    const nextBtn = document.querySelector(".slider-next");
    let currentSlide = 0;

    function showSlide(n) {
        slides.forEach((slide) => slide.classList.remove("active"));
        dots.forEach((dot) => dot.classList.remove("active"));

        if (n >= slides.length) currentSlide = 0;
        if (n < 0) currentSlide = slides.length - 1;

        slides[currentSlide].classList.add("active");
        dots[currentSlide].classList.add("active");
    }

    prevBtn.addEventListener("click", () => {
        currentSlide--;
        showSlide(currentSlide);
    });

    nextBtn.addEventListener("click", () => {
        currentSlide++;
        showSlide(currentSlide);
    });

    dots.forEach((dot, index) => {
        dot.addEventListener("click", () => {
            currentSlide = index;
            showSlide(currentSlide);
        });
    });
});

<?php
$images = get_field('project_gallery');

if ($images) :
    ?>
    <div class="responsive-gallery">
        <?php foreach ($images as $image) : ?>
            <div class="gallery-item">
                <picture>
                    <!-- Mobile: thumbnail -->
                    <source media="(max-width: 480px)"
                            srcset="<?php echo esc_url($image['sizes']['thumbnail']); ?>">

                    <!-- Tablet: medium -->
                    <source media="(max-width: 768px)"
                            srcset="<?php echo esc_url($image['sizes']['medium']); ?>">

                    <!-- Desktop: large -->
                    <img src="<?php echo esc_url($image['sizes']['large']); ?>"
                         alt="<?php echo esc_attr($image['alt']); ?>" />
                </picture>
            </div>
        <?php endforeach; ?>
    </div>
<?php endif; ?>

<?php
$images = get_field('project_gallery');

if ($images) :
    ?>
    <div class="gallery-with-thumbs">
        <!-- Main Display -->
        <div class="main-image">
            <img id="main-gallery-img"
                 src="<?php echo esc_url($images[0]['sizes']['large']); ?>"
                 alt="<?php echo esc_attr($images[0]['alt']); ?>" />
        </div>

        <!-- Thumbnails -->
        <div class="thumbnail-strip">
            <?php foreach ($images as $index => $image) : ?>
                <button class="thumb <?php echo ($index === 0) ? 'active' : ''; ?>"
                        data-full="<?php echo esc_url($image['sizes']['large']); ?>"
                        data-alt="<?php echo esc_attr($image['alt']); ?>">
                    <img src="<?php echo esc_url($image['sizes']['thumbnail']); ?>"
                         alt="<?php echo esc_attr($image['alt']); ?>" />
                </button>
            <?php endforeach; ?>
        </div>
    </div>
<?php endif; ?>

document.querySelectorAll(".thumb").forEach(function (thumb) {
    thumb.addEventListener("click", function () {
        const fullSrc = this.getAttribute("data-full");
        const altText = this.getAttribute("data-alt");
        const mainImg = document.getElementById("main-gallery-img");

        mainImg.src = fullSrc;
        mainImg.alt = altText;

        document.querySelectorAll(".thumb").forEach((t) => t.classList.remove("active"));
        this.classList.add("active");
    });
});

<?php
$images = get_field('project_gallery');

if ($images) :
    ?>
    <div class="lazy-gallery">
        <?php foreach ($images as $index => $image) :
            // Load first 3 images immediately, lazy load rest
            $loading = ($index < 3) ? 'eager' : 'lazy';
            ?>

            <div class="gallery-item">
                <img src="<?php echo esc_url($image['sizes']['medium']); ?>"
                     alt="<?php echo esc_attr($image['alt']); ?>"
                     loading="<?php echo esc_attr($loading); ?>"
                     width="<?php echo esc_attr($image['sizes']['medium-width']); ?>"
                     height="<?php echo esc_attr($image['sizes']['medium-height']); ?>" />
            </div>

        <?php endforeach; ?>
    </div>
<?php endif; ?>

<?php
$images = get_field('project_gallery');

if ($images) :
    ?>
    <div class="filtered-gallery">
        <!-- Category Filters -->
        <div class="gallery-filters">
            <button class="filter-btn active" data-filter="all">All</button>
            <button class="filter-btn" data-filter="product">Product</button>
            <button class="filter-btn" data-filter="lifestyle">Lifestyle</button>
            <button class="filter-btn" data-filter="detail">Detail</button>
        </div>

        <!-- Gallery Items -->
        <div class="gallery-grid">
            <?php foreach ($images as $image) :
                // Get category from image description
                $category = $image['description'] ?: 'all';
                ?>

                <div class="gallery-item" data-category="<?php echo esc_attr($category); ?>">
                    <img src="<?php echo esc_url($image['sizes']['medium']); ?>"
                         alt="<?php echo esc_attr($image['alt']); ?>" />
                </div>

            <?php endforeach; ?>
        </div>
    </div>
<?php endif; ?>

document.querySelectorAll(".filter-btn").forEach(function (btn) {
    btn.addEventListener("click", function () {
        const filter = this.getAttribute("data-filter");

        document.querySelectorAll(".filter-btn").forEach((b) => b.classList.remove("active"));
        this.classList.add("active");

        document.querySelectorAll(".gallery-item").forEach(function (item) {
            const category = item.getAttribute("data-category");

            if (filter === "all" || category === filter) {
                item.style.display = "block";
            } else {
                item.style.display = "none";
            }
        });
    });
});

<?php
$images = get_field('project_gallery');

if ($images) :
    $image_count = count($images);
    ?>

    <div class="gallery-section">
        <div class="gallery-header">
            <h2>Project Gallery</h2>
            <p class="image-count">
                <?php echo esc_html($image_count); ?>
                <?php echo ($image_count === 1) ? 'Image' : 'Images'; ?>
            </p>
        </div>

        <div class="image-gallery">
            <?php foreach ($images as $image) : ?>
                <div class="gallery-item">
                    <img src="<?php echo esc_url($image['sizes']['medium']); ?>"
                         alt="<?php echo esc_attr($image['alt']); ?>" />
                </div>
            <?php endforeach; ?>
        </div>
    </div>

<?php endif; ?>

<?php
$images = get_field('project_gallery');

if ($images) :
    foreach ($images as $image) :
        // Available image data:
        $id = $image['ID'];
        $title = $image['title'];
        $alt = $image['alt'];
        $caption = $image['caption'];
        $description = $image['description'];
        $url = $image['url'];
        $width = $image['width'];
        $height = $image['height'];

        // Image sizes
        $thumbnail = $image['sizes']['thumbnail'];
        $medium = $image['sizes']['medium'];
        $large = $image['sizes']['large'];
        $full = $image['sizes']['full'];

        // Size dimensions
        $thumb_width = $image['sizes']['thumbnail-width'];
        $thumb_height = $image['sizes']['thumbnail-height'];
    endforeach;
endif;
?>

function mytheme_register_gallery_field() {
    if (function_exists('acf_add_local_field_group')) {
        acf_add_local_field_group(array(
            'key'    => 'group_project_gallery',
            'title'  => 'Project Gallery',
            'fields' => array(
                array(
                    'key'    => 'field_project_gallery',
                    'label'  => 'Gallery Images',
                    'name'   => 'project_gallery',
                    'type'   => 'gallery',
                    'return_format' => 'array',
                    'library' => 'all',
                    'min'    => 1,
                    'max'    => 50,
                    'insert' => 'append',
                ),
            ),
            'location' => array(
                array(
                    array(
                        'param'    => 'post_type',
                        'operator' => '==',
                        'value'    => 'portfolio',
                    ),
                ),
            ),
        ));
    }
}
add_action('acf/init', 'mytheme_register_gallery_field');

<?php
$images = get_field('project_gallery');

// Good - check before loop
if ($images) {
    foreach ($images as $image) {
        // Display images
    }
}

// Bad - no check, may cause errors
foreach (get_field('project_gallery') as $image) {
    // Display images
}
?>

// Use appropriate size for context
$thumbnail = $image['sizes']['thumbnail']; // 150x150
$medium = $image['sizes']['medium'];       // 300x300
$large = $image['sizes']['large'];         // 1024x1024

<?php echo esc_url($image['url']); ?>
<?php echo esc_attr($image['alt']); ?>
<?php echo esc_html($image['caption']); ?>

<?php
if (have_rows('page_content')) :

    while (have_rows('page_content')) : the_row();

        if (get_row_layout() == 'text_block') :
            // Text Block Layout
            $heading = get_sub_field('heading');
            $content = get_sub_field('content');
            $alignment = get_sub_field('alignment');
            ?>

            <section class="content-block text-block text-<?php echo esc_attr($alignment); ?>">
                <?php if ($heading) : ?>
                    <h2><?php echo esc_html($heading); ?></h2>
                <?php endif; ?>

                <?php if ($content) : ?>
                    <div class="content">
                        <?php echo wp_kses_post($content); ?>
                    </div>
                <?php endif; ?>
            </section>

        <?php elseif (get_row_layout() == 'image_block') :
            // Image Block Layout
            $image = get_sub_field('image');
            $caption = get_sub_field('caption');
            $size = get_sub_field('size');
            ?>

            <section class="content-block image-block size-<?php echo esc_attr($size); ?>">
                <?php if ($image) : ?>
                    <figure>
                        <img src="<?php echo esc_url($image['sizes'][$size]); ?>"
                             alt="<?php echo esc_attr($image['alt']); ?>" />
                        <?php if ($caption) : ?>
                            <figcaption><?php echo esc_html($caption); ?></figcaption>
                        <?php endif; ?>
                    </figure>
                <?php endif; ?>
            </section>

        <?php elseif (get_row_layout() == 'gallery') :
            // Gallery Layout
            $images = get_sub_field('images');
            $columns = get_sub_field('columns');
            ?>

            <section class="content-block gallery-block columns-<?php echo esc_attr($columns); ?>">
                <?php if ($images) : ?>
                    <div class="gallery-grid">
                        <?php foreach ($images as $image) : ?>
                            <div class="gallery-item">
                                <img src="<?php echo esc_url($image['sizes']['medium']); ?>"
                                     alt="<?php echo esc_attr($image['alt']); ?>" />
                            </div>
                        <?php endforeach; ?>
                    </div>
                <?php endif; ?>
            </section>

        <?php endif;

    endwhile;

endif;
?>

<?php
if (have_rows('page_content')) :

    while (have_rows('page_content')) : the_row();

        // Text Block
        if (get_row_layout() == 'text_block') :
            get_template_part('template-parts/blocks/text-block');

        // Hero Section
        elseif (get_row_layout() == 'hero') :
            $title = get_sub_field('hero_title');
            $subtitle = get_sub_field('hero_subtitle');
            $background = get_sub_field('background_image');
            $button_text = get_sub_field('button_text');
            $button_link = get_sub_field('button_link');
            ?>

            <section class="content-block hero-block"
                     style="background-image: url(<?php echo esc_url($background['url']); ?>);">
                <div class="hero-content">
                    <?php if ($title) : ?>
                        <h1><?php echo esc_html($title); ?></h1>
                    <?php endif; ?>

                    <?php if ($subtitle) : ?>
                        <p class="subtitle"><?php echo esc_html($subtitle); ?></p>
                    <?php endif; ?>

                    <?php if ($button_text && $button_link) : ?>
                        <a href="<?php echo esc_url($button_link); ?>" class="btn btn-primary">
                            <?php echo esc_html($button_text); ?>
                        </a>
                    <?php endif; ?>
                </div>
            </section>

        // Two Column Layout
        elseif (get_row_layout() == 'two_columns') :
            $left_content = get_sub_field('left_column');
            $right_content = get_sub_field('right_column');
            ?>

            <section class="content-block two-columns">
                <div class="row">
                    <div class="col-left">
                        <?php echo wp_kses_post($left_content); ?>
                    </div>
                    <div class="col-right">
                        <?php echo wp_kses_post($right_content); ?>
                    </div>
                </div>
            </section>

        // Testimonials
        elseif (get_row_layout() == 'testimonials') :
            if (have_rows('testimonial_items')) :
                ?>
                <section class="content-block testimonials-block">
                    <div class="testimonials-grid">
                        <?php while (have_rows('testimonial_items')) : the_row();
                            $quote = get_sub_field('quote');
                            $author = get_sub_field('author');
                            $company = get_sub_field('company');
                            $photo = get_sub_field('photo');
                            ?>

                            <div class="testimonial">
                                <blockquote>
                                    <?php echo esc_html($quote); ?>
                                </blockquote>

                                <div class="testimonial-author">
                                    <?php if ($photo) : ?>
                                        <img src="<?php echo esc_url($photo['sizes']['thumbnail']); ?>"
                                             alt="<?php echo esc_attr($author); ?>" />
                                    <?php endif; ?>

                                    <div class="author-info">
                                        <strong><?php echo esc_html($author); ?></strong>
                                        <?php if ($company) : ?>
                                            <span><?php echo esc_html($company); ?></span>
                                        <?php endif; ?>
                                    </div>
                                </div>
                            </div>

                        <?php endwhile; ?>
                    </div>
                </section>
            <?php endif;

        // Call to Action
        elseif (get_row_layout() == 'cta') :
            $heading = get_sub_field('cta_heading');
            $text = get_sub_field('cta_text');
            $button = get_sub_field('cta_button');
            $background_color = get_sub_field('background_color');
            ?>

            <section class="content-block cta-block"
                     style="background-color: <?php echo esc_attr($background_color); ?>;">
                <div class="cta-content">
                    <?php if ($heading) : ?>
                        <h2><?php echo esc_html($heading); ?></h2>
                    <?php endif; ?>

                    <?php if ($text) : ?>
                        <p><?php echo esc_html($text); ?></p>
                    <?php endif; ?>

                    <?php if ($button) : ?>
                        <a href="<?php echo esc_url($button['url']); ?>" class="btn btn-large">
                            <?php echo esc_html($button['title']); ?>
                        </a>
                    <?php endif; ?>
                </div>
            </section>

        <?php endif;

    endwhile;

endif;
?>

<?php
if (have_rows('page_content')) :
    while (have_rows('page_content')) : the_row();

        $layout = get_row_layout();

        // Load template part based on layout name
        get_template_part('template-parts/blocks/' . $layout);

    endwhile;
endif;
?>

<?php
$heading = get_sub_field('heading');
$content = get_sub_field('content');
$alignment = get_sub_field('alignment');
?>

<section class="content-block text-block text-<?php echo esc_attr($alignment); ?>">
    <?php if ($heading) : ?>
        <h2><?php echo esc_html($heading); ?></h2>
    <?php endif; ?>

    <?php if ($content) : ?>
        <div class="content">
            <?php echo wp_kses_post($content); ?>
        </div>
    <?php endif; ?>
</section>

function mytheme_register_flexible_content() {
    if (function_exists('acf_add_local_field_group')) {
        acf_add_local_field_group(array(
            'key'    => 'group_page_builder',
            'title'  => 'Page Builder',
            'fields' => array(
                array(
                    'key'    => 'field_page_content',
                    'label'  => 'Page Content',
                    'name'   => 'page_content',
                    'type'   => 'flexible_content',
                    'button_label' => 'Add Content Block',
                    'layouts' => array(
                        'text_block' => array(
                            'key'   => 'layout_text_block',
                            'name'  => 'text_block',
                            'label' => 'Text Block',
                            'display' => 'block',
                            'sub_fields' => array(
                                array(
                                    'key'   => 'field_heading',
                                    'label' => 'Heading',
                                    'name'  => 'heading',
                                    'type'  => 'text',
                                ),
                                array(
                                    'key'   => 'field_content',
                                    'label' => 'Content',
                                    'name'  => 'content',
                                    'type'  => 'wysiwyg',
                                ),
                            ),
                        ),
                        'image_block' => array(
                            'key'   => 'layout_image_block',
                            'name'  => 'image_block',
                            'label' => 'Image Block',
                            'display' => 'block',
                            'sub_fields' => array(
                                array(
                                    'key'   => 'field_image',
                                    'label' => 'Image',
                                    'name'  => 'image',
                                    'type'  => 'image',
                                    'return_format' => 'array',
                                ),
                                array(
                                    'key'   => 'field_caption',
                                    'label' => 'Caption',
                                    'name'  => 'caption',
                                    'type'  => 'text',
                                ),
                            ),
                        ),
                    ),
                ),
            ),
            'location' => array(
                array(
                    array(
                        'param'    => 'post_type',
                        'operator' => '==',
                        'value'    => 'page',
                    ),
                ),
            ),
        ));
    }
}
add_action('acf/init', 'mytheme_register_flexible_content');

<?php
$layout_index = 0;

if (have_rows('page_content')) :
    while (have_rows('page_content')) : the_row();
        $layout_index++;
        $layout = get_row_layout();

        // Add special class to first layout
        $first_class = ($layout_index === 1) ? 'first-block' : '';

        // Add container to specific layouts only
        $needs_container = in_array($layout, array('text_block', 'cta'));
        ?>

        <section class="content-block <?php echo esc_attr($layout); ?> <?php echo esc_attr($first_class); ?>">
            <?php if ($needs_container) : ?>
                <div class="container">
            <?php endif; ?>

            <?php
            // Display layout content
            get_template_part('template-parts/blocks/' . $layout);
            ?>

            <?php if ($needs_container) : ?>
                </div>
            <?php endif; ?>
        </section>

    <?php endwhile;
endif;
?>

<?php
if (have_rows('page_content')) :
    while (have_rows('page_content')) : the_row();

        if (get_row_layout() == 'section_with_blocks') :
            $section_title = get_sub_field('section_title');
            ?>

            <section class="multi-block-section">
                <h2><?php echo esc_html($section_title); ?></h2>

                <?php
                // Nested flexible content
                if (have_rows('section_blocks')) :
                    while (have_rows('section_blocks')) : the_row();

                        if (get_row_layout() == 'feature') :
                            $feature_icon = get_sub_field('icon');
                            $feature_title = get_sub_field('title');
                            $feature_text = get_sub_field('text');
                            ?>

                            <div class="feature">
                                <?php if ($feature_icon) : ?>
                                    <img src="<?php echo esc_url($feature_icon['url']); ?>" alt="" />
                                <?php endif; ?>
                                <h3><?php echo esc_html($feature_title); ?></h3>
                                <p><?php echo esc_html($feature_text); ?></p>
                            </div>

                        <?php endif;

                    endwhile;
                endif;
                ?>
            </section>

        <?php endif;

    endwhile;
endif;
?>

<?php
if (have_rows('page_content')) :
    while (have_rows('page_content')) : the_row();

        $layout = get_row_layout();
        $custom_class = get_sub_field('custom_css_class');
        $background_color = get_sub_field('background_color');
        $padding = get_sub_field('padding_size');

        $classes = array(
            'content-block',
            $layout,
            $custom_class,
            'padding-' . $padding,
        );

        $style = $background_color ? 'background-color: ' . esc_attr($background_color) : '';
        ?>

        <section class="<?php echo esc_attr(implode(' ', array_filter($classes))); ?>"
                 <?php if ($style) : ?>style="<?php echo $style; ?>"<?php endif; ?>>
            <?php get_template_part('template-parts/blocks/' . $layout); ?>
        </section>

    <?php endwhile;
endif;
?>

// Create base layout configuration
acf_add_local_field_group(array(
    'key' => 'group_block_settings',
    'title' => 'Block Settings',
    'fields' => array(
        array(
            'key' => 'field_block_settings',
            'label' => 'Block Settings',
            'name' => 'block_settings',
            'type' => 'group',
            'sub_fields' => array(
                array(
                    'key' => 'field_margin',
                    'label' => 'Margin',
                    'name' => 'margin',
                    'type' => 'select',
                    'choices' => array(
                        'none' => 'None',
                        'small' => 'Small',
                        'medium' => 'Medium',
                        'large' => 'Large',
                    ),
                ),
                array(
                    'key' => 'field_animation',
                    'label' => 'Animation',
                    'name' => 'animation',
                    'type' => 'select',
                    'choices' => array(
                        'none' => 'None',
                        'fade-in' => 'Fade In',
                        'slide-up' => 'Slide Up',
                    ),
                ),
            ),
        ),
    ),
));

// Clone in flexible content layouts
array(
    'key' => 'field_settings_clone',
    'label' => 'Settings',
    'name' => 'settings',
    'type' => 'clone',
    'clone' => array('field_block_settings'),
)

theme/
├── template-parts/
│   └── blocks/
│       ├── text_block.php
│       ├── image_block.php
│       ├── gallery.php
│       ├── hero.php
│       ├── testimonials.php
│       └── cta.php

<?php echo esc_html($text); ?>
<?php echo esc_url($url); ?>
<?php echo esc_attr($class); ?>
<?php echo wp_kses_post($html_content); ?>

Traditional Field Group:
- Attached to post type
- Single metabox location
- Fixed field order

ACF Block:
- Insertable anywhere in content
- Multiple instances per post
- Drag-and-drop positioning
- Reusable patterns

function mytheme_register_acf_blocks() {
    // Check ACF function exists
    if (function_exists('acf_register_block_type')) {
        acf_register_block_type(array(
            'name' => 'testimonial',
            'title' => __('Testimonial', 'mytheme'),
            'description' => __('A custom testimonial block', 'mytheme'),
            'render_template' => get_template_directory() . '/blocks/testimonial.php',
            'category' => 'common',
            'icon' => 'format-quote',
            'keywords' => array('testimonial', 'quote', 'review'),
        ));
    }
}
add_action('acf/init', 'mytheme_register_acf_blocks');

acf_register_block_type(array(
    // Required
    'name' => 'testimonial',
    'title' => __('Testimonial'),

    // Content
    'description' => __('A testimonial block'),
    'render_template' => 'blocks/testimonial.php',
    'render_callback' => 'mytheme_render_testimonial',

    // Appearance
    'category' => 'common',
    'icon' => 'format-quote',
    'keywords' => array('testimonial'),

    // Behavior
    'mode' => 'preview',
    'align' => 'full',
    'supports' => array(
        'align' => true,
        'mode' => false,
        'multiple' => true,
        'jsx' => true,
    ),

    // Style
    'enqueue_style' => get_template_directory_uri() . '/blocks/testimonial.css',
    'enqueue_script' => get_template_directory_uri() . '/blocks/testimonial.js',
    'enqueue_assets' => 'mytheme_testimonial_assets',

    // Advanced
    'post_types' => array('post', 'page'),
    'example' => array(
        'attributes' => array(
            'mode' => 'preview',
            'data' => array(
                'author' => 'John Doe',
                'quote' => 'Amazing service!',
            ),
        ),
    ),
));

name: Unique slug (no spaces)
title: Display name in inserter
description: Block description
render_template: PHP file path
render_callback: PHP function name
category: Block category
icon: Dashicon or custom SVG
keywords: Search terms
mode: 'preview', 'edit', or 'auto'
align: Default alignment
supports: Block capabilities
enqueue_style: CSS file URL
enqueue_script: JS file URL
post_types: Allowed post types
example: Preview data

<?php
/**
 * Testimonial Block Template
 *
 * @param array $block The block settings and attributes
 * @param string $content The block inner HTML (empty)
 * @param bool $is_preview True during AJAX preview
 * @param int $post_id The post ID this block is saved to
 */

// Get ACF fields
$author = get_field('author');
$company = get_field('company');
$quote = get_field('quote');
$photo = get_field('photo');
$rating = get_field('rating');

// Block ID
$block_id = 'testimonial-' . $block['id'];

// Block classes
$class_name = 'testimonial-block';
if (!empty($block['className'])) {
    $class_name .= ' ' . $block['className'];
}
if (!empty($block['align'])) {
    $class_name .= ' align' . $block['align'];
}
?>

<div id="<?php echo esc_attr($block_id); ?>" class="<?php echo esc_attr($class_name); ?>">
    <?php if ($quote) : ?>
        <blockquote class="testimonial-quote">
            <?php echo esc_html($quote); ?>
        </blockquote>
    <?php endif; ?>

    <div class="testimonial-author">
        <?php if ($photo) : ?>
            <img src="<?php echo esc_url($photo['sizes']['thumbnail']); ?>"
                 alt="<?php echo esc_attr($author); ?>"
                 class="author-photo" />
        <?php endif; ?>

        <div class="author-info">
            <?php if ($author) : ?>
                <strong class="author-name"><?php echo esc_html($author); ?></strong>
            <?php endif; ?>

            <?php if ($company) : ?>
                <span class="author-company"><?php echo esc_html($company); ?></span>
            <?php endif; ?>

            <?php if ($rating) : ?>
                <div class="rating">
                    <?php for ($i = 0; $i < $rating; $i++) : ?>
                        <span class="star">★</span>
                    <?php endfor; ?>
                </div>
            <?php endif; ?>
        </div>
    </div>
</div>

function mytheme_register_block_fields() {
    if (function_exists('acf_add_local_field_group')) {
        acf_add_local_field_group(array(
            'key' => 'group_testimonial_block',
            'title' => 'Testimonial Block Fields',
            'fields' => array(
                array(
                    'key' => 'field_author',
                    'label' => 'Author',
                    'name' => 'author',
                    'type' => 'text',
                    'required' => 1,
                ),
                array(
                    'key' => 'field_company',
                    'label' => 'Company',
                    'name' => 'company',
                    'type' => 'text',
                ),
                array(
                    'key' => 'field_quote',
                    'label' => 'Quote',
                    'name' => 'quote',
                    'type' => 'textarea',
                    'required' => 1,
                ),
                array(
                    'key' => 'field_photo',
                    'label' => 'Photo',
                    'name' => 'photo',
                    'type' => 'image',
                    'return_format' => 'array',
                ),
                array(
                    'key' => 'field_rating',
                    'label' => 'Rating',
                    'name' => 'rating',
                    'type' => 'range',
                    'min' => 1,
                    'max' => 5,
                    'step' => 1,
                    'default_value' => 5,
                ),
            ),
            'location' => array(
                array(
                    array(
                        'param' => 'block',
                        'operator' => '==',
                        'value' => 'acf/testimonial',
                    ),
                ),
            ),
        ));
    }
}
add_action('acf/init', 'mytheme_register_block_fields');

'common' - Common
'formatting' - Formatting
'layout' - Layout
'widgets' - Widgets
'embed' - Embeds

function mytheme_block_categories($categories) {
    return array_merge(
        $categories,
        array(
            array(
                'slug' => 'custom-blocks',
                'title' => __('Custom Blocks', 'mytheme'),
                'icon' => 'admin-customizer',
            ),
        )
    );
}
add_filter('block_categories_all', 'mytheme_block_categories', 10, 2);

'icon' => 'format-quote'
'icon' => 'admin-users'
'icon' => 'heart'

'icon' => '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 2L2 7v10c0 5.55 3.84 10.74 9 12 5.16-1.26 9-6.45 9-12V7l-10-5z"/></svg>'

'icon' => array(
    'background' => '#7e70af',
    'foreground' => '#fff',
    'src' => 'format-quote',
)

// Preview mode (default)
'mode' => 'preview'

// Edit mode (show fields)
'mode' => 'edit'

// Auto switch
'mode' => 'auto'

'supports' => array(
    'mode' => true, // Allow users to toggle
)

'align' => 'full'
'align' => 'wide'
'align' => 'center'

'supports' => array(
    'align' => true, // Enable alignment toolbar
    'align' => array('left', 'center', 'right'), // Specific alignments
)

'supports' => array(
    'jsx' => true,
)

<div class="container-block">
    <div class="container-header">
        <h2><?php echo esc_html(get_field('title')); ?></h2>
    </div>

    <div class="container-content">
        <InnerBlocks />
    </div>
</div>

'example' => array(
    'attributes' => array(
        'mode' => 'preview',
        'data' => array(
            'author' => 'Jane Smith',
            'company' => 'Acme Corp',
            'quote' => 'This is an amazing product!',
            'rating' => '5',
        ),
    ),
)

'enqueue_style' => get_template_directory_uri() . '/blocks/testimonial.css',
'enqueue_script' => get_template_directory_uri() . '/blocks/testimonial.js',

'enqueue_assets' => function() {
    wp_enqueue_style('testimonial-block', get_template_directory_uri() . '/blocks/testimonial.css');
    wp_enqueue_script('testimonial-block', get_template_directory_uri() . '/blocks/testimonial.js', array('jquery'), '1.0', true);
}

'render_callback' => 'mytheme_render_testimonial'

function mytheme_render_testimonial($block, $content = '', $is_preview = false, $post_id = 0) {
    $author = get_field('author');
    $quote = get_field('quote');

    echo '<div class="testimonial-block">';
    echo '<blockquote>' . esc_html($quote) . '</blockquote>';
    echo '<cite>' . esc_html($author) . '</cite>';
    echo '</div>';
}

<?php
$block_attributes = get_block_wrapper_attributes(array(
    'class' => 'additional-class',
    'data-custom' => 'value',
));
?>

<div <?php echo $block_attributes; ?>>
    <!-- Block content -->
</div>

'post_types' => array('post', 'page')
'post_types' => array('portfolio')

'supports' => array(
    'multiple' => true, // Allow multiple instances
)

'supports' => array(
    'multiple' => false, // Single instance only
)

function mytheme_register_template() {
    $post_type_object = get_post_type_object('portfolio');
    $post_type_object->template = array(
        array('acf/testimonial', array(
            'author' => 'Default Author',
            'quote' => 'Add your testimonial here',
        )),
        array('core/paragraph', array(
            'placeholder' => 'Add project description...',
        )),
    );
}
add_action('init', 'mytheme_register_template');

// Registration
acf_register_block_type(array(
    'name' => 'hero',
    'title' => __('Hero Section'),
    'render_template' => 'blocks/hero.php',
    'category' => 'layout',
    'icon' => 'cover-image',
    'supports' => array(
        'align' => array('full'),
        'mode' => false,
    ),
));

// Fields
acf_add_local_field_group(array(
    'key' => 'group_hero',
    'title' => 'Hero Block',
    'fields' => array(
        array(
            'key' => 'field_hero_title',
            'label' => 'Title',
            'name' => 'title',
            'type' => 'text',
        ),
        array(
            'key' => 'field_hero_subtitle',
            'label' => 'Subtitle',
            'name' => 'subtitle',
            'type' => 'text',
        ),
        array(
            'key' => 'field_hero_bg',
            'label' => 'Background Image',
            'name' => 'background_image',
            'type' => 'image',
            'return_format' => 'url',
        ),
        array(
            'key' => 'field_hero_button',
            'label' => 'Button',
            'name' => 'button',
            'type' => 'link',
        ),
    ),
    'location' => array(
        array(
            array(
                'param' => 'block',
                'operator' => '==',
                'value' => 'acf/hero',
            ),
        ),
    ),
));

<?php
$title = get_field('title');
$subtitle = get_field('subtitle');
$bg_image = get_field('background_image');
$button = get_field('button');

$class_name = 'hero-block';
if (!empty($block['className'])) {
    $class_name .= ' ' . $block['className'];
}
?>

<section class="<?php echo esc_attr($class_name); ?>"
         style="background-image: url(<?php echo esc_url($bg_image); ?>);">
    <div class="hero-content">
        <?php if ($title) : ?>
            <h1 class="hero-title"><?php echo esc_html($title); ?></h1>
        <?php endif; ?>

        <?php if ($subtitle) : ?>
            <p class="hero-subtitle"><?php echo esc_html($subtitle); ?></p>
        <?php endif; ?>

        <?php if ($button) : ?>
            <a href="<?php echo esc_url($button['url']); ?>"
               class="hero-button"
               target="<?php echo esc_attr($button['target'] ?: '_self'); ?>">
                <?php echo esc_html($button['title']); ?>
            </a>
        <?php endif; ?>
    </div>
</section>